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/tracing/user_events_status and can both register and write 15data out via /sys/kernel/tracing/user_events_data. 16 17Programs can also use /sys/kernel/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/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/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/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/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/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/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