man2/perfmonctl.2

   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>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .TH PERFMONCTL 2 2021-03-22 Linux "Linux Programmer's Manual"
  28 .SH NAME
  29 perfmonctl \- interface to IA-64 performance monitoring unit
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <syscall.h>
  33 .B #include <perfmon.h>
  34 .PP
  35 .BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg ");"
  36 .fi
  37 .PP
  38 .IR Note :
  39 There is no glibc wrapper for this system call; see NOTES.
  40 .SH DESCRIPTION
  41 The IA-64-specific
  42 .BR perfmonctl ()
  43 system call provides an interface to the
  44 PMU (performance monitoring unit).
  45 The PMU consists of PMD (performance monitoring data) registers and
  46 PMC (performance monitoring control) registers,
  47 which gather hardware statistics.
  48 .PP
  49 .BR perfmonctl ()
  50 applies the operation
  51 .I cmd
  52 to the input arguments specified by
  53 .IR arg .
  54 The number of arguments is defined by \fInarg\fR.
  55 The
  56 .I fd
  57 argument specifies the perfmon context to operate on.
  58 .PP
  59 Supported values for
  60 .I cmd
  61 are:
  62 .TP
  63 .B PFM_CREATE_CONTEXT
  64 .nf
  65 .BI  "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);"
  66 .fi
  67 Set up a context.
  68 .IP
  69 The
  70 .I fd
  71 parameter is ignored.
  72 A new perfmon context is created as specified in
  73 .I ctxt
  74 and its file descriptor is returned in \fIctxt->ctx_fd\fR.
  75 .IP
  76 The file descriptor can be used in subsequent calls to
  77 .BR perfmonctl ()
  78 and can be used to read event notifications (type
  79 .IR pfm_msg_t )
  80 using
  81 .BR read (2).
  82 The file descriptor is pollable using
  83 .BR select (2),
  84 .BR poll (2),
  85 and
  86 .BR epoll (7).
  87 .IP
  88 The context can be destroyed by calling
  89 .BR close (2)
  90 on the file descriptor.
  91 .TP
  92 .B PFM_WRITE_PMCS
  93 .\" pfm_write_pmcs()
  94 .nf
  95 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);"
  96 .fi
  97 Set PMC registers.
  98 .TP
  99 .B PFM_WRITE_PMDS
 100 .nf
 101 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);"
 102 .fi
 103 .\" pfm_write_pmds()
 104 Set PMD registers.
 105 .TP
 106 .B PFM_READ_PMDS
 107 .\" pfm_read_pmds()
 108 .nf
 109 .BI  "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);"
 110 .fi
 111 Read PMD registers.
 112 .TP
 113 .B PFM_START
 114 .\" pfm_start()
 115 .nf
 116 .\" .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
 117 .BI  "perfmonctl(int " fd ", PFM_START, NULL, 0);"
 118 .fi
 119 Start monitoring.
 120 .TP
 121 .B PFM_STOP
 122 .\" pfm_stop()
 123 .nf
 124 .BI  "perfmonctl(int " fd ", PFM_STOP, NULL, 0);"
 125 .fi
 126 Stop monitoring.
 127 .TP
 128 .B PFM_LOAD_CONTEXT
 129 .\" pfm_context_load()
 130 .nf
 131 .BI  "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);"
 132 .fi
 133 Attach the context to a thread.
 134 .TP
 135 .B PFM_UNLOAD_CONTEXT
 136 .\" pfm_context_unload()
 137 .nf
 138 .BI  "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);"
 139 .fi
 140 Detach the context from a thread.
 141 .TP
 142 .B PFM_RESTART
 143 .\" pfm_restart()
 144 .nf
 145 .BI  "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);"
 146 .fi
 147 Restart monitoring after receiving an overflow notification.
 148 .TP
 149 .B PFM_GET_FEATURES
 150 .\" pfm_get_features()
 151 .nf
 152 .BI  "perfmonctl(int " fd ", PFM_GET_FEATURES, pfarg_features_t *" arg ", 1);"
 153 .fi
 154 .TP
 155 .B PFM_DEBUG
 156 .\" pfm_debug()
 157 .nf
 158 .BI  "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0);"
 159 .fi
 160 If
 161 .I val
 162 is nonzero, enable debugging mode, otherwise disable.
 163 .TP
 164 .B PFM_GET_PMC_RESET_VAL
 165 .\" pfm_get_pmc_reset()
 166 .nf
 167 .BI  "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t *" req  ", n);"
 168 .fi
 169 Reset PMC registers to default values.
 170 .\"
 171 .\"
 172 .\" .TP
 173 .\" .B PFM_CREATE_EVTSETS
 174 .\"
 175 .\" create or modify event sets
 176 .\" .nf
 177 .\" .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
 178 .\" .fi
 179 .\" .TP
 180 .\" .B PFM_DELETE_EVTSETS
 181 .\" delete event sets
 182 .\" .nf
 183 .\" .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
 184 .\" .fi
 185 .\" .TP
 186 .\" .B PFM_GETINFO_EVTSETS
 187 .\" get information about event sets
 188 .\" .nf
 189 .\" .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
 190 .\" .fi
 191 .SH RETURN VALUE
 192 .BR perfmonctl ()
 193 returns zero when the operation is successful.
 194 On error, \-1 is returned and
 195 .I errno
 196 is set to indicate the error.
 197 .SH VERSIONS
 198 .BR perfmonctl ()
 199 was added in Linux 2.4;
 200 .\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7
 201 it was removed in Linux 5.10.
 202 .SH CONFORMING TO
 203 .BR perfmonctl ()
 204 is Linux-specific and is available only on the IA-64 architecture.
 205 .SH NOTES
 206 This system call was broken for many years,
 207 and ultimately removed in Linux 5.10.
 208 .PP
 209 Glibc does not provide a wrapper for this system call;
 210 on kernels where it exists, call it using
 211 .BR syscall (2).
 212 .SH SEE ALSO
 213 .BR gprof (1)
 214 .PP
 215 The perfmon2 interface specification