original/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 2013-02-13 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 .sp
  35 .BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg ");
  36 .fi
  37 .IR Note :
  38 There is no glibc wrapper for this system call; see NOTES.
  39 .SH DESCRIPTION
  40 The IA-64-specific
  41 .BR perfmonctl ()
  42 system call provides an interface to the
  43 PMU (performance monitoring unit).
  44 The PMU consists of PMD (performance monitoring data) registers and
  45 PMC (performance monitoring control) registers,
  46 which gather hardware statistics.
  47
  48 .BR perfmonctl ()
  49 applies the operation
  50 .I cmd
  51 to the input arguments specified by
  52 .IR arg .
  53 The number of arguments is defined by \fInarg\fR.
  54 The
  55 .I fd
  56 argument specifies the perfmon context to operate on.
  57
  58 Supported values for
  59 .I cmd
  60 are:
  61 .TP
  62 .B PFM_CREATE_CONTEXT
  63 .nf
  64 .BI  "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);
  65 .fi
  66 Set up a context.
  67
  68 The
  69 .I fd
  70 parameter is ignored.
  71 A new perfmon context is created as specified in
  72 .I ctxt
  73 and its file descriptor is returned in \fIctxt->ctx_fd\fR.
  74
  75 The file descriptor can be used in subsequent calls to
  76 .BR perfmonctl ()
  77 and can be used to read event notifications (type
  78 .IR pfm_msg_t )
  79 using
  80 .BR read (2).
  81 The file descriptor is pollable using
  82 .BR select (2),
  83 .BR poll (2),
  84 and
  85 .BR epoll (7).
  86
  87 The context can be destroyed by calling
  88 .BR close (2)
  89 on the file descriptor.
  90 .TP
  91 .B PFM_WRITE_PMCS
  92 .\" pfm_write_pmcs()
  93 .nf
  94 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);
  95 .fi
  96 Set PMC registers.
  97 .TP
  98 .B PFM_WRITE_PMDS
  99 .nf
 100 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);
 101 .fi
 102 .\" pfm_write_pmds()
 103 Set PMD registers.
 104 .TP
 105 .B PFM_READ_PMDS
 106 .\" pfm_read_pmds()
 107 .nf
 108 .BI  "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);
 109 .fi
 110 Read PMD registers.
 111 .TP
 112 .B PFM_START
 113 .\" pfm_start()
 114 .nf
 115 .\" .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
 116 .BI  "perfmonctl(int " fd ", PFM_START, NULL, 0);
 117 .fi
 118 Start monitoring.
 119 .TP
 120 .B PFM_STOP
 121 .\" pfm_stop()
 122 .nf
 123 .BI  "perfmonctl(int " fd ", PFM_STOP, NULL, 0);
 124 .fi
 125 Stop monitoring.
 126 .TP
 127 .B PFM_LOAD_CONTEXT
 128 .\" pfm_context_load()
 129 .nf
 130 .BI  "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);
 131 .fi
 132 Attach the context to a thread.
 133 .TP
 134 .B PFM_UNLOAD_CONTEXT
 135 .\" pfm_context_unload()
 136 .nf
 137 .BI  "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);
 138 .fi
 139 Detach the context from a thread.
 140 .TP
 141 .B PFM_RESTART
 142 .\" pfm_restart()
 143 .nf
 144 .BI  "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);
 145 .fi
 146 Restart monitoring after receiving an overflow notification.
 147 .TP
 148 .B PFM_GET_FEATURES
 149 .\" pfm_get_features()
 150 .nf
 151 .BI  "perfmonctl(int " fd ", PFM_GET_FEARURES, pfarg_features_t *" arg ", 1);
 152 .fi
 153 .TP
 154 .B PFM_DEBUG
 155 .\" pfm_debug()
 156 .nf
 157 .BI  "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0);
 158 .fi
 159 If
 160 .I val
 161 is nonzero, enable debugging mode, otherwise disable.
 162 .TP
 163 .B PFM_GET_PMC_RESET_VAL
 164 .\" pfm_get_pmc_reset()
 165 .nf
 166 .BI  "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t * " req  ", n);
 167 .fi
 168 Reset PMC registers to default values.
 169 .\"
 170 .\"
 171 .\" .TP
 172 .\" .B PFM_CREATE_EVTSETS
 173 .\"
 174 .\" create or modify event sets
 175 .\" .nf
 176 .\" .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
 177 .\" .fi
 178 .\" .TP
 179 .\" .B PFM_DELETE_EVTSETS
 180 .\" delete event sets
 181 .\" .nf
 182 .\" .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
 183 .\" .fi
 184 .\" .TP
 185 .\" .B PFM_GETINFO_EVTSETS
 186 .\" get information about event sets
 187 .\" .nf
 188 .\" .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
 189 .\" .fi
 190 .SH RETURN VALUE
 191 .BR perfmonctl ()
 192 returns zero when the operation is successful.
 193 On error, \-1 is returned and
 194 .I errno
 195 is set to indicate the cause of the error.
 196 .SH VERSIONS
 197 .BR perfmonctl ()
 198 is available since Linux 2.4.
 199 .SH CONFORMING TO
 200 .BR perfmonctl ()
 201 is Linux-specific and is available only on the IA-64 architecture.
 202 .SH NOTES
 203 Glibc does not provide a wrapper for this system call; call it using
 204 .BR syscall (2).
 205 .SH SEE ALSO
 206 .BR gprof (1)
 207
 208 The perfmon2 interface specification
 209 .SH COLOPHON
 210 This page is part of release 3.67 of the Linux
 211 .I man-pages
 212 project.
 213 A description of the project,
 214 information about reporting bugs,
 215 and the latest version of this page,
 216 can be found at
 217 \%http://www.kernel.org/doc/man\-pages/.