@@ -14,6 +14,11 @@ Programs can view status of the events via
1414/sys/kernel/tracing/user_events_status and can both register and write
1515data out via /sys/kernel/tracing/user_events_data.
1616
17+ Programs can also use /sys/kernel/tracing/dynamic_events to register and
18+ delete user based events via the u: prefix. The format of the command to
19+ dynamic_events is the same as the ioctl with the u: prefix applied. This
20+ requires CAP_PERFMON due to the event persisting, otherwise -EPERM is returned.
21+
1722Typically programs will register a set of events that they wish to expose to
1823tools that can read trace_events (such as ftrace and perf). The registration
1924process tells the kernel which address and bit to reflect if any tool has
@@ -45,7 +50,7 @@ This command takes a packed struct user_reg as an argument::
4550 /* Input: Enable size in bytes at address */
4651 __u8 enable_size;
4752
48- /* Input: Flags for future use, set to 0 */
53+ /* Input: Flags to use, if any */
4954 __u16 flags;
5055
5156 /* Input: Address to update when enabled */
@@ -69,7 +74,7 @@ The struct user_reg requires all the above inputs to be set appropriately.
6974 This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be
7075 used on 64-bit kernels, however, 32-bit can be used on all kernels.
7176
72- + flags: The flags to use, if any. For the initial version this must be 0.
77+ + flags: The flags to use, if any.
7378 Callers should first attempt to use flags and retry without flags to ensure
7479 support for lower versions of the kernel. If a flag is not supported -EINVAL
7580 is returned.
@@ -80,6 +85,13 @@ The struct user_reg requires all the above inputs to be set appropriately.
8085+ name_args: The name and arguments to describe the event, see command format
8186 for details.
8287
88+ The following flags are currently supported.
89+
90+ + USER_EVENT_REG_PERSIST: The event will not delete upon the last reference
91+ closing. Callers may use this if an event should exist even after the
92+ process closes or unregisters the event. Requires CAP_PERFMON otherwise
93+ -EPERM is returned.
94+
8395Upon successful registration the following is set.
8496
8597+ write_index: The index to use for this file descriptor that represents this
@@ -141,7 +153,10 @@ event (in both user and kernel space). User programs should use a separate file
141153to request deletes than the one used for registration due to this.
142154
143155**NOTE: ** By default events will auto-delete when there are no references left
144- to the event. Flags in the future may change this logic.
156+ to the event. If programs do not want auto-delete, they must use the
157+ USER_EVENT_REG_PERSIST flag when registering the event. Once that flag is used
158+ the event exists until DIAG_IOCSDEL is invoked. Both register and delete of an
159+ event that persists requires CAP_PERFMON, otherwise -EPERM is returned.
145160
146161Unregistering
147162-------------
0 commit comments