| blob | d1c4c8c2a6a0bca382190d26eb161f459837c6a5 |
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 2017-09-15 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 .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 .PP
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 .PP
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 .IP
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 .IP
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 .IP
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_FEATURES, 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 .PP
208 The perfmon2 interface specification