1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
2 .\" and Copyright (C) 2013 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" Written by Ivana Varekova <varekova@redhat.com>
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .TH PERFMONCTL 2 2021-03-22 Linux "Linux Programmer's Manual"
9 perfmonctl \- interface to IA-64 performance monitoring unit
12 .B #include <syscall.h>
13 .B #include <perfmon.h>
15 .BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg ");"
19 There is no glibc wrapper for this system call; see NOTES.
23 system call provides an interface to the
24 PMU (performance monitoring unit).
25 The PMU consists of PMD (performance monitoring data) registers and
26 PMC (performance monitoring control) registers,
27 which gather hardware statistics.
32 to the input arguments specified by
34 The number of arguments is defined by \fInarg\fR.
37 argument specifies the perfmon context to operate on.
45 .BI "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);"
52 A new perfmon context is created as specified in
54 and its file descriptor is returned in \fIctxt->ctx_fd\fR.
56 The file descriptor can be used in subsequent calls to
58 and can be used to read event notifications (type
62 The file descriptor is pollable using
68 The context can be destroyed by calling
70 on the file descriptor.
75 .BI "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);"
81 .BI "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);"
89 .BI "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);"
96 .\" .BI "perfmonctl(int " fd ", PFM_START, arg, 1);
97 .BI "perfmonctl(int " fd ", PFM_START, NULL, 0);"
104 .BI "perfmonctl(int " fd ", PFM_STOP, NULL, 0);"
109 .\" pfm_context_load()
111 .BI "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);"
113 Attach the context to a thread.
115 .B PFM_UNLOAD_CONTEXT
116 .\" pfm_context_unload()
118 .BI "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);"
120 Detach the context from a thread.
125 .BI "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);"
127 Restart monitoring after receiving an overflow notification.
130 .\" pfm_get_features()
132 .BI "perfmonctl(int " fd ", PFM_GET_FEATURES, pfarg_features_t *" arg ", 1);"
138 .BI "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0);"
142 is nonzero, enable debugging mode, otherwise disable.
144 .B PFM_GET_PMC_RESET_VAL
145 .\" pfm_get_pmc_reset()
147 .BI "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t *" req ", n);"
149 Reset PMC registers to default values.
153 .\" .B PFM_CREATE_EVTSETS
155 .\" create or modify event sets
157 .\" .BI "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
160 .\" .B PFM_DELETE_EVTSETS
161 .\" delete event sets
163 .\" .BI "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
166 .\" .B PFM_GETINFO_EVTSETS
167 .\" get information about event sets
169 .\" .BI "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
173 returns zero when the operation is successful.
174 On error, \-1 is returned and
176 is set to indicate the error.
179 was added in Linux 2.4;
180 .\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7
181 it was removed in Linux 5.10.
184 is Linux-specific and is available only on the IA-64 architecture.
186 This system call was broken for many years,
187 and ultimately removed in Linux 5.10.
189 Glibc does not provide a wrapper for this system call;
190 on kernels where it exists, call it using
195 The perfmon2 interface specification