man2/perfmonctl.2

.\" 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 2017-09-15 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>
.PP
.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.
.PP
.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.
.PP
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.
.IP
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.
.IP
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).
.IP
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)
.PP
The perfmon2 interface specification