1 =========================================
2 user_events: User-based Event Tracing
3 =========================================
4
5 :Author: Beau Belgrave
6
7 Overview
8 --------
9 User based trace events allow user processes t
10 that can be viewed via existing tools, such as
11 To enable this feature, build your kernel with
12
13 Programs can view status of the events via
14 /sys/kernel/tracing/user_events_status and can
15 data out via /sys/kernel/tracing/user_events_d
16
17 Programs can also use /sys/kernel/tracing/dyna
18 delete user based events via the u: prefix. Th
19 dynamic_events is the same as the ioctl with t
20 requires CAP_PERFMON due to the event persisti
21
22 Typically programs will register a set of even
23 tools that can read trace_events (such as ftra
24 process tells the kernel which address and bit
25 enabled the event and data should be written.
26 a write index which describes the data when a
27 on the /sys/kernel/tracing/user_events_data fi
28
29 The structures referenced in this document are
30 /include/uapi/linux/user_events.h file in the
31
32 **NOTE:** *Both user_events_status and user_ev
33 filesystem and may be mounted at different pat
34
35 Registering
36 -----------
37 Registering within a user process is done via
38 /sys/kernel/tracing/user_events_data file. The
39 DIAG_IOCSREG.
40
41 This command takes a packed struct user_reg as
42
43 struct user_reg {
44 /* Input: Size of the user_reg structu
45 __u32 size;
46
47 /* Input: Bit in enable address to use
48 __u8 enable_bit;
49
50 /* Input: Enable size in bytes at addr
51 __u8 enable_size;
52
53 /* Input: Flags to use, if any */
54 __u16 flags;
55
56 /* Input: Address to update when enabl
57 __u64 enable_addr;
58
59 /* Input: Pointer to string with event
60 __u64 name_args;
61
62 /* Output: Index of the event to use w
63 __u32 write_index;
64 } __attribute__((__packed__));
65
66 The struct user_reg requires all the above inp
67
68 + size: This must be set to sizeof(struct user
69
70 + enable_bit: The bit to reflect the event sta
71 enable_addr.
72
73 + enable_size: The size of the value specified
74 This must be 4 (32-bit) or 8 (64-bit). 64-bi
75 used on 64-bit kernels, however, 32-bit can
76
77 + flags: The flags to use, if any.
78 Callers should first attempt to use flags an
79 support for lower versions of the kernel. If
80 is returned.
81
82 + enable_addr: The address of the value to use
83 must be naturally aligned and write accessib
84
85 + name_args: The name and arguments to describ
86 for details.
87
88 The following flags are currently supported.
89
90 + USER_EVENT_REG_PERSIST: The event will not d
91 closing. Callers may use this if an event sh
92 process closes or unregisters the event. Req
93 -EPERM is returned.
94
95 + USER_EVENT_REG_MULTI_FORMAT: The event can c
96 allows programs to prevent themselves from b
97 format changes and they wish to use the same
98 tracepoint name will be in the new format of
99 format of "name". A tracepoint will be creat
100 and format. This means if several processes
101 they will use the same tracepoint. If yet an
102 but a different format than the other proces
103 tracepoint with a new unique id. Recording p
104 the various different formats of the event n
105 recording. The system name of the tracepoint
106 instead of "user_events". This prevents sing
107 with any multi-format event names within tra
108 a hex string. Recording programs should ensu
109 the event name they registered and has a suf
110 has hex characters. For example to find all
111 can use the regex "^test\.[0-9a-fA-F]+$".
112
113 Upon successful registration the following is
114
115 + write_index: The index to use for this file
116 event when writing out data. The index is un
117 descriptor that was used for the registratio
118
119 User based events show up under tracefs like a
120 subsystem named "user_events". This means tool
121 events need to use /sys/kernel/tracing/events/
122 or perf record -e user_events:[name] when atta
123
124 **NOTE:** The event subsystem name by default
125 not assume it will always be "user_events". Op
126 future to change the subsystem name per-proces
127 In addition if the USER_EVENT_REG_MULTI_FORMAT
128 will have a unique id appended to it and the s
129 "user_events_multi" as described above.
130
131 Command Format
132 ^^^^^^^^^^^^^^
133 The command string format is as follows::
134
135 name[:FLAG1[,FLAG2...]] [Field1[;Field2...]]
136
137 Supported Flags
138 ^^^^^^^^^^^^^^^
139 None yet
140
141 Field Format
142 ^^^^^^^^^^^^
143 ::
144
145 type name [size]
146
147 Basic types are supported (__data_loc, u32, u6
148 User programs are encouraged to use clearly si
149
150 **NOTE:** *Long is not supported since size ca
151
152 The size is only valid for types that start wi
153 This allows user programs to describe custom s
154
155 For example, a struct in C that looks like thi
156
157 struct mytype {
158 char data[20];
159 };
160
161 Would be represented by the following field::
162
163 struct mytype myname 20
164
165 Deleting
166 --------
167 Deleting an event from within a user process i
168 /sys/kernel/tracing/user_events_data file. The
169 DIAG_IOCSDEL.
170
171 This command only requires a single string spe
172 its name. Delete will only succeed if there ar
173 event (in both user and kernel space). User pr
174 to request deletes than the one used for regis
175
176 **NOTE:** By default events will auto-delete w
177 to the event. If programs do not want auto-del
178 USER_EVENT_REG_PERSIST flag when registering t
179 the event exists until DIAG_IOCSDEL is invoked
180 event that persists requires CAP_PERFMON, othe
181 there are multiple formats of the same event n
182 name will be attempted to be deleted. If only
183 be deleted then the /sys/kernel/tracing/dynami
184 that specific format of the event.
185
186 Unregistering
187 -------------
188 If after registering an event it is no longer
189 be disabled via ioctl() out to the /sys/kernel
190 The command to issue is DIAG_IOCSUNREG. This i
191 deleting actually removes the event from the s
192 the kernel your process is no longer intereste
193
194 This command takes a packed struct user_unreg
195
196 struct user_unreg {
197 /* Input: Size of the user_unreg struc
198 __u32 size;
199
200 /* Input: Bit to unregister */
201 __u8 disable_bit;
202
203 /* Input: Reserved, set to 0 */
204 __u8 __reserved;
205
206 /* Input: Reserved, set to 0 */
207 __u16 __reserved2;
208
209 /* Input: Address to unregister */
210 __u64 disable_addr;
211 } __attribute__((__packed__));
212
213 The struct user_unreg requires all the above i
214
215 + size: This must be set to sizeof(struct user
216
217 + disable_bit: This must be set to the bit to
218 previously registered via enable_bit).
219
220 + disable_addr: This must be set to the addres
221 previously registered via enable_addr).
222
223 **NOTE:** Events are automatically unregistere
224 fork() the registered events will be retained
225 in each process if wanted.
226
227 Status
228 ------
229 When tools attach/record user based events the
230 in realtime. This allows user programs to only
231 writev() calls when something is actively atta
232
233 The kernel will update the specified bit that
234 tools attach/detach from the event. User progr
235 to see if something is attached or not.
236
237 Administrators can easily check the status of
238 the user_events_status file directly via a ter
239
240 Name [# Comments]
241 ...
242
243 Active: ActiveCount
244 Busy: BusyCount
245
246 For example, on a system that has a single eve
247
248 test
249
250 Active: 1
251 Busy: 0
252
253 If a user enables the user event via ftrace, t
254
255 test # Used by ftrace
256
257 Active: 1
258 Busy: 1
259
260 Writing Data
261 ------------
262 After registering an event the same fd that wa
263 to write an entry for that event. The write_in
264 of the data, then the remaining data is treate
265
266 For example, if write_index returned was 1 and
267 payload of the event. Then the data would have
268 with the first 4 bytes being equal to 1 and th
269 value I want as the payload.
270
271 In memory this would look like this::
272
273 int index;
274 int payload;
275
276 User programs might have well known structs th
277 as payloads. In those cases writev() can be us
278 the index and the following vector(s) being th
279
280 For example, if I have a struct like this::
281
282 struct payload {
283 int src;
284 int dst;
285 int flags;
286 } __attribute__((__packed__));
287
288 It's advised for user programs to do the follo
289
290 struct iovec io[2];
291 struct payload e;
292
293 io[0].iov_base = &write_index;
294 io[0].iov_len = sizeof(write_index);
295 io[1].iov_base = &e;
296 io[1].iov_len = sizeof(e);
297
298 writev(fd, (const struct iovec*)io, 2);
299
300 **NOTE:** *The write_index is not emitted out
301
302 Example Code
303 ------------
304 See sample code in samples/user_events.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.