2013-02-09 19:03:34 +00:00
|
|
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
|
|
|
.\" Written by Ivana Varekova <varekova@redhat.com>
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\"
|
2013-02-09 20:28:49 +00:00
|
|
|
.TH PERFMONCTL 2 2013-02-10 Linux "Linux Programmer's Manual"
|
2013-02-09 19:03:34 +00:00
|
|
|
.SH NAME
|
2013-02-09 20:28:49 +00:00
|
|
|
perfmonctl \- interface to IA-64 performance monitoring unit
|
2013-02-09 19:03:34 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <syscall.h>
|
|
|
|
.B #include <perfmon.h>
|
|
|
|
.sp
|
|
|
|
.BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg ");
|
|
|
|
.fi
|
2013-02-09 20:34:04 +00:00
|
|
|
.IR Note :
|
|
|
|
There is no glibc wrapper for this system call; see NOTES.
|
2013-02-09 19:03:34 +00:00
|
|
|
.SH DESCRIPTION
|
2013-02-09 20:28:49 +00:00
|
|
|
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.
|
2013-02-09 19:03:34 +00:00
|
|
|
|
2013-02-09 20:28:49 +00:00
|
|
|
.BR perfmonctl ()
|
|
|
|
applies the operation
|
2013-02-09 19:03:34 +00:00
|
|
|
.I cmd
|
2013-02-09 20:28:49 +00:00
|
|
|
to the input arguments specified by
|
|
|
|
.IR arg .
|
|
|
|
The number of arguments is defined by \fInarg\fR.
|
|
|
|
The
|
2013-02-09 19:03:34 +00:00
|
|
|
.I fd
|
2013-02-09 20:28:49 +00:00
|
|
|
argument specifies the perfmon context to operate on.
|
2013-02-09 19:03:34 +00:00
|
|
|
|
2013-02-09 20:28:49 +00:00
|
|
|
Supported values for
|
2013-02-09 19:03:34 +00:00
|
|
|
.I cmd
|
|
|
|
are:
|
|
|
|
|
|
|
|
.TP
|
|
|
|
.B PFM_CREATE_CONTEXT
|
|
|
|
set up a context
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
|
|
|
|
The
|
|
|
|
.I fd
|
2013-02-09 20:28:49 +00:00
|
|
|
parameter is ignored.
|
|
|
|
A new perfmon context is created as specified in
|
2013-02-09 19:03:34 +00:00
|
|
|
.I ctxt
|
|
|
|
and its file descriptor is returned in \fIctxt->ctx_fd\fR.
|
|
|
|
|
|
|
|
The file descriptor, apart from passing it to \fBperfmonctl\fR,
|
|
|
|
can be used to read event notifications (type
|
|
|
|
\fBpfm_msg_t\fR) using the
|
|
|
|
.BR read (2)
|
|
|
|
system call.
|
|
|
|
Both
|
|
|
|
.BR select (2)
|
|
|
|
and
|
|
|
|
.BR poll (2)
|
|
|
|
can be used to wait for event notifications.
|
|
|
|
|
|
|
|
The context can be destroyed using the
|
|
|
|
.BR close (2)
|
|
|
|
system call.
|
|
|
|
.TP
|
|
|
|
.B PFM_WRITE_PMCS
|
2013-02-09 20:28:49 +00:00
|
|
|
.\" pfm_write_pmcs()
|
2013-02-09 19:03:34 +00:00
|
|
|
set PMC registers
|
|
|
|
.nf
|
2013-02-09 20:36:15 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
2013-02-09 20:28:49 +00:00
|
|
|
.B PFM_WRITE_PMDS
|
|
|
|
.\" pfm_write_pmds()
|
2013-02-09 19:03:34 +00:00
|
|
|
set PMD registers
|
|
|
|
.nf
|
2013-02-09 20:36:15 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
2013-02-09 20:28:49 +00:00
|
|
|
.B PFM_READ_PMDS
|
|
|
|
.\" pfm_read_pmds()
|
2013-02-09 19:03:34 +00:00
|
|
|
read PMD registers
|
|
|
|
.nf
|
2013-02-09 20:36:15 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
2013-02-09 20:28:49 +00:00
|
|
|
.B PFM_START
|
|
|
|
.\" pfm_start()
|
2013-02-09 19:03:34 +00:00
|
|
|
start monitoring
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.\" .BI "perfmonctl(int " fd ", PFM_START, arg, 1);
|
|
|
|
.BI "perfmonctl(int " fd ", PFM_START, NULL, 0);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
|
|
|
.B PFM_STOP
|
2013-02-09 20:28:49 +00:00
|
|
|
.\" pfm_stop()
|
2013-02-09 19:03:34 +00:00
|
|
|
stop monitoring
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_START, NULL, 0);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
2013-02-09 20:28:49 +00:00
|
|
|
.B PFM_LOAD_CONTEXT
|
|
|
|
.\" pfm_context_load()
|
2013-02-09 19:03:34 +00:00
|
|
|
attach the context to a thread
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
|
|
|
.B PFM_UNLOAD_CONTEXT
|
2013-02-09 20:28:49 +00:00
|
|
|
.\" pfm_context_unload()
|
2013-02-09 19:03:34 +00:00
|
|
|
detach the context from a thread
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
|
|
|
.TP
|
|
|
|
.B PFM_RESTART
|
2013-02-09 20:28:49 +00:00
|
|
|
.\" pfm_restart()
|
2013-02-09 19:03:34 +00:00
|
|
|
restart monitoring after receiving an overflow notification
|
|
|
|
.nf
|
2013-02-09 20:28:49 +00:00
|
|
|
.BI "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);
|
2013-02-09 19:03:34 +00:00
|
|
|
.fi
|
2013-02-09 20:30:03 +00:00
|
|
|
.\"
|
|
|
|
.\" PFM_GET_FEATURES - pfm_get_features()
|
|
|
|
.\" PFM_DEBUG - pfm_debug()
|
|
|
|
.\" PFM_GET_PMC_RESET_VAL - pfm_get_pmc_reset()
|
|
|
|
.\"
|
|
|
|
.\"
|
2013-02-09 20:29:24 +00:00
|
|
|
.\" .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
|
2013-02-09 19:03:34 +00:00
|
|
|
|
|
|
|
.SH "RETURN VALUE"
|
2013-02-09 20:28:49 +00:00
|
|
|
.BR performctl ()
|
2013-02-09 19:03:34 +00:00
|
|
|
returns zero when the operation is successful.
|
2013-02-09 20:34:43 +00:00
|
|
|
On error, \-1 is returned and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the cause of the error.
|
2013-02-09 19:03:34 +00:00
|
|
|
|
2013-02-09 20:32:51 +00:00
|
|
|
.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.
|
2013-02-09 19:03:34 +00:00
|
|
|
|
2013-02-09 20:34:04 +00:00
|
|
|
.SH NOTES
|
|
|
|
Glibc does not provide a wrapper for this system call; call it using
|
|
|
|
.BR syscall (2).
|
|
|
|
|
2013-02-09 19:03:34 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR gprof(1),
|
|
|
|
The perfmon2 interface specification
|