1=========================================
2user_events: User-based Event Tracing
3=========================================
4
5:Author: Beau Belgrave
6
7Overview
8--------
9User based trace events allow user processes to create events and trace data
10that can be viewed via existing tools, such as ftrace and perf.
11To enable this feature, build your kernel with CONFIG_USER_EVENTS=y.
12
13Programs can view status of the events via
14/sys/kernel/debug/tracing/user_events_status and can both register and write
15data out via /sys/kernel/debug/tracing/user_events_data.
16
17Programs can also use /sys/kernel/debug/tracing/dynamic_events to register and
18delete user based events via the u: prefix. The format of the command to
19dynamic_events is the same as the ioctl with the u: prefix applied.
20
21Typically programs will register a set of events that they wish to expose to
22tools that can read trace_events (such as ftrace and perf). The registration
23process gives back two ints to the program for each event. The first int is
24the status bit. This describes which bit in little-endian format in the
25/sys/kernel/debug/tracing/user_events_status file represents this event. The
26second int is the write index which describes the data when a write() or
27writev() is called on the /sys/kernel/debug/tracing/user_events_data file.
28
29The structures referenced in this document are contained within the
30/include/uapi/linux/user_events.h file in the source tree.
31
32**NOTE:** *Both user_events_status and user_events_data are under the tracefs
33filesystem and may be mounted at different paths than above.*
34
35Registering
36-----------
37Registering within a user process is done via ioctl() out to the
38/sys/kernel/debug/tracing/user_events_data file. The command to issue is
39DIAG_IOCSREG.
40
41This command takes a packed struct user_reg as an argument::
42
43  struct user_reg {
44        u32 size;
45        u64 name_args;
46        u32 status_bit;
47        u32 write_index;
48  };
49
50The struct user_reg requires two inputs, the first is the size of the structure
51to ensure forward and backward compatibility. The second is the command string
52to issue for registering. Upon success two outputs are set, the status bit
53and the write index.
54
55User based events show up under tracefs like any other event under the
56subsystem named "user_events". This means tools that wish to attach to the
57events need to use /sys/kernel/debug/tracing/events/user_events/[name]/enable
58or perf record -e user_events:[name] when attaching/recording.
59
60**NOTE:** *The write_index returned is only valid for the FD that was used*
61
62Command Format
63^^^^^^^^^^^^^^
64The command string format is as follows::
65
66  name[:FLAG1[,FLAG2...]] [Field1[;Field2...]]
67
68Supported Flags
69^^^^^^^^^^^^^^^
70None yet
71
72Field Format
73^^^^^^^^^^^^
74::
75
76  type name [size]
77
78Basic types are supported (__data_loc, u32, u64, int, char, char[20], etc).
79User programs are encouraged to use clearly sized types like u32.
80
81**NOTE:** *Long is not supported since size can vary between user and kernel.*
82
83The size is only valid for types that start with a struct prefix.
84This allows user programs to describe custom structs out to tools, if required.
85
86For example, a struct in C that looks like this::
87
88  struct mytype {
89    char data[20];
90  };
91
92Would be represented by the following field::
93
94  struct mytype myname 20
95
96Deleting
97-----------
98Deleting an event from within a user process is done via ioctl() out to the
99/sys/kernel/debug/tracing/user_events_data file. The command to issue is
100DIAG_IOCSDEL.
101
102This command only requires a single string specifying the event to delete by
103its name. Delete will only succeed if there are no references left to the
104event (in both user and kernel space). User programs should use a separate file
105to request deletes than the one used for registration due to this.
106
107Status
108------
109When tools attach/record user based events the status of the event is updated
110in realtime. This allows user programs to only incur the cost of the write() or
111writev() calls when something is actively attached to the event.
112
113User programs call mmap() on /sys/kernel/debug/tracing/user_events_status to
114check the status for each event that is registered. The bit to check in the
115file is given back after the register ioctl() via user_reg.status_bit. The bit
116is always in little-endian format. Programs can check if the bit is set either
117using a byte-wise index with a mask or a long-wise index with a little-endian
118mask.
119
120Currently the size of user_events_status is a single page, however, custom
121kernel configurations can change this size to allow more user based events. In
122all cases the size of the file is a multiple of a page size.
123
124For example, if the register ioctl() gives back a status_bit of 3 you would
125check byte 0 (3 / 8) of the returned mmap data and then AND the result with 8
126(1 << (3 % 8)) to see if anything is attached to that event.
127
128A byte-wise index check is performed as follows::
129
130  int index, mask;
131  char *status_page;
132
133  index = status_bit / 8;
134  mask = 1 << (status_bit % 8);
135
136  ...
137
138  if (status_page[index] & mask) {
139        /* Enabled */
140  }
141
142A long-wise index check is performed as follows::
143
144  #include <asm/bitsperlong.h>
145  #include <endian.h>
146
147  #if __BITS_PER_LONG == 64
148  #define endian_swap(x) htole64(x)
149  #else
150  #define endian_swap(x) htole32(x)
151  #endif
152
153  long index, mask, *status_page;
154
155  index = status_bit / __BITS_PER_LONG;
156  mask = 1L << (status_bit % __BITS_PER_LONG);
157  mask = endian_swap(mask);
158
159  ...
160
161  if (status_page[index] & mask) {
162        /* Enabled */
163  }
164
165Administrators can easily check the status of all registered events by reading
166the user_events_status file directly via a terminal. The output is as follows::
167
168  Byte:Name [# Comments]
169  ...
170
171  Active: ActiveCount
172  Busy: BusyCount
173  Max: MaxCount
174
175For example, on a system that has a single event the output looks like this::
176
177  1:test
178
179  Active: 1
180  Busy: 0
181  Max: 32768
182
183If a user enables the user event via ftrace, the output would change to this::
184
185  1:test # Used by ftrace
186
187  Active: 1
188  Busy: 1
189  Max: 32768
190
191**NOTE:** *A status bit of 0 will never be returned. This allows user programs
192to have a bit that can be used on error cases.*
193
194Writing Data
195------------
196After registering an event the same fd that was used to register can be used
197to write an entry for that event. The write_index returned must be at the start
198of the data, then the remaining data is treated as the payload of the event.
199
200For example, if write_index returned was 1 and I wanted to write out an int
201payload of the event. Then the data would have to be 8 bytes (2 ints) in size,
202with the first 4 bytes being equal to 1 and the last 4 bytes being equal to the
203value I want as the payload.
204
205In memory this would look like this::
206
207  int index;
208  int payload;
209
210User programs might have well known structs that they wish to use to emit out
211as payloads. In those cases writev() can be used, with the first vector being
212the index and the following vector(s) being the actual event payload.
213
214For example, if I have a struct like this::
215
216  struct payload {
217        int src;
218        int dst;
219        int flags;
220  };
221
222It's advised for user programs to do the following::
223
224  struct iovec io[2];
225  struct payload e;
226
227  io[0].iov_base = &write_index;
228  io[0].iov_len = sizeof(write_index);
229  io[1].iov_base = &e;
230  io[1].iov_len = sizeof(e);
231
232  writev(fd, (const struct iovec*)io, 2);
233
234**NOTE:** *The write_index is not emitted out into the trace being recorded.*
235
236Example Code
237------------
238See sample code in samples/user_events.
239