mirror of https://github.com/mkerrisk/man-pages
209 lines
5.3 KiB
Groff
209 lines
5.3 KiB
Groff
.\" 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_FEATURES, 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
|