diff options
Diffstat (limited to '')
| -rw-r--r-- | Documentation/trace/events.rst | 133 |
1 files changed, 82 insertions, 51 deletions
diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index ed79b220bd07..c47f381d0c00 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -198,6 +198,15 @@ The glob (~) accepts a wild card character (\*,?) and character classes prev_comm ~ "*sh*" prev_comm ~ "ba*sh" +If the field is a pointer that points into user space (for example +"filename" from sys_enter_openat), then you have to append ".ustring" to the +field name:: + + filename.ustring ~ "password" + +As the kernel will have to know how to retrieve the memory that the pointer +is at from user space. + 5.2 Setting filters ------------------- @@ -230,6 +239,16 @@ Currently the caret ('^') for an error always appears at the beginning of the filter string; the error message should still be useful though even without more accurate position info. +5.2.1 Filter limitations +------------------------ + +If a filter is placed on a string pointer ``(char *)`` that does not point +to a string on the ring buffer, but instead points to kernel or user space +memory, then, for safety reasons, at most 1024 bytes of the content is +copied onto a temporary buffer to do the compare. If the copy of the memory +faults (the pointer points to memory that should not be accessed), then the +string compare will be treated as not matching. + 5.3 Clearing filters -------------------- @@ -342,7 +361,8 @@ section of Documentation/trace/ftrace.rst), but there are major differences and the implementation isn't currently tied to it in any way, so beware about making generalizations between the two. -Note: Writing into trace_marker (See Documentation/trace/ftrace.rst) +.. Note:: + Writing into trace_marker (See Documentation/trace/ftrace.rst) can also enable triggers that are written into /sys/kernel/tracing/events/ftrace/print/trigger @@ -526,8 +546,8 @@ The following commands are supported: See Documentation/trace/histogram.rst for details and examples. -6.3 In-kernel trace event API ------------------------------ +7. In-kernel trace event API +============================ In most cases, the command-line interface to trace events is more than sufficient. Sometimes, however, applications might find the need for @@ -559,8 +579,8 @@ following: - tracing synthetic events from in-kernel code - the low-level "dynevent_cmd" API -6.3.1 Dyamically creating synthetic event definitions ------------------------------------------------------ +7.1 Dyamically creating synthetic event definitions +--------------------------------------------------- There are a couple ways to create a new synthetic event from a kernel module or other kernel code. @@ -569,14 +589,14 @@ The first creates the event in one step, using synth_event_create(). In this method, the name of the event to create and an array defining the fields is supplied to synth_event_create(). If successful, a synthetic event with that name and fields will exist following that -call. For example, to create a new "schedtest" synthetic event: +call. For example, to create a new "schedtest" synthetic event:: ret = synth_event_create("schedtest", sched_fields, ARRAY_SIZE(sched_fields), THIS_MODULE); The sched_fields param in this example points to an array of struct synth_field_desc, each of which describes an event field by type and -name: +name:: static struct synth_field_desc sched_fields[] = { { .type = "pid_t", .name = "next_pid_field" }, @@ -588,8 +608,19 @@ name: { .type = "int", .name = "my_int_field" }, }; -See synth_field_size() for available types. If field_name contains [n] -the field is considered to be an array. +See synth_field_size() for available types. + +If field_name contains [n], the field is considered to be a static array. + +If field_names contains[] (no subscript), the field is considered to +be a dynamic array, which will only take as much space in the event as +is required to hold the array. + +Because space for an event is reserved before assigning field values +to the event, using dynamic arrays implies that the piecewise +in-kernel API described below can't be used with dynamic arrays. The +other non-piecewise in-kernel APIs can, however, be used with dynamic +arrays. If the event is created from within a module, a pointer to the module must be passed to synth_event_create(). This will ensure that the @@ -615,7 +646,7 @@ synth_event_gen_cmd_array_start(), the user should create and initialize a dynevent_cmd object using synth_event_cmd_init(). For example, to create a new "schedtest" synthetic event with two -fields: +fields:: struct dynevent_cmd cmd; char *buf; @@ -631,7 +662,7 @@ fields: "u64", "ts_ns"); Alternatively, using an array of struct synth_field_desc fields -containing the same information: +containing the same information:: ret = synth_event_gen_cmd_array_start(&cmd, "schedtest", THIS_MODULE, fields, n_fields); @@ -640,7 +671,7 @@ Once the synthetic event object has been created, it can then be populated with more fields. Fields are added one by one using synth_event_add_field(), supplying the dynevent_cmd object, a field type, and a field name. For example, to add a new int field named -"intfield", the following call should be made: +"intfield", the following call should be made:: ret = synth_event_add_field(&cmd, "int", "intfield"); @@ -649,7 +680,7 @@ the field is considered to be an array. A group of fields can also be added all at once using an array of synth_field_desc with add_synth_fields(). For example, this would add -just the first four sched_fields: +just the first four sched_fields:: ret = synth_event_add_fields(&cmd, sched_fields, 4); @@ -658,15 +689,15 @@ synth_event_add_field_str() can be used to add it as-is; it will also automatically append a ';' to the string. Once all the fields have been added, the event should be finalized and -registered by calling the synth_event_gen_cmd_end() function: +registered by calling the synth_event_gen_cmd_end() function:: ret = synth_event_gen_cmd_end(&cmd); At this point, the event object is ready to be used for tracing new events. -6.3.3 Tracing synthetic events from in-kernel code --------------------------------------------------- +7.2 Tracing synthetic events from in-kernel code +------------------------------------------------ To trace a synthetic event, there are several options. The first option is to trace the event in one call, using synth_event_trace() @@ -677,8 +708,8 @@ synth_event_trace_start() and synth_event_trace_end() along with synth_event_add_next_val() or synth_event_add_val() to add the values piecewise. -6.3.3.1 Tracing a synthetic event all at once ---------------------------------------------- +7.2.1 Tracing a synthetic event all at once +------------------------------------------- To trace a synthetic event all at once, the synth_event_trace() or synth_event_trace_array() functions can be used. @@ -691,7 +722,7 @@ trace array)), along with an variable number of u64 args, one for each synthetic event field, and the number of values being passed. So, to trace an event corresponding to the synthetic event definition -above, code like the following could be used: +above, code like the following could be used:: ret = synth_event_trace(create_synth_test, 7, /* number of values */ 444, /* next_pid_field */ @@ -715,7 +746,7 @@ trace array)), along with an array of u64, one for each synthetic event field. To trace an event corresponding to the synthetic event definition -above, code like the following could be used: +above, code like the following could be used:: u64 vals[7]; @@ -739,7 +770,7 @@ In order to trace a synthetic event, a pointer to the trace event file is needed. The trace_get_event_file() function can be used to get it - it will find the file in the given trace instance (in this case NULL since the top trace array is being used) while at the same time -preventing the instance containing it from going away: +preventing the instance containing it from going away:: schedtest_event_file = trace_get_event_file(NULL, "synthetic", "schedtest"); @@ -751,48 +782,48 @@ To enable a synthetic event from the kernel, trace_array_set_clr_event() can be used (which is not specific to synthetic events, so does need the "synthetic" system name to be specified explicitly). -To enable the event, pass 'true' to it: +To enable the event, pass 'true' to it:: trace_array_set_clr_event(schedtest_event_file->tr, "synthetic", "schedtest", true); -To disable it pass false: +To disable it pass false:: trace_array_set_clr_event(schedtest_event_file->tr, "synthetic", "schedtest", false); Finally, synth_event_trace_array() can be used to actually trace the -event, which should be visible in the trace buffer afterwards: +event, which should be visible in the trace buffer afterwards:: ret = synth_event_trace_array(schedtest_event_file, vals, ARRAY_SIZE(vals)); To remove the synthetic event, the event should be disabled, and the -trace instance should be 'put' back using trace_put_event_file(): +trace instance should be 'put' back using trace_put_event_file():: trace_array_set_clr_event(schedtest_event_file->tr, "synthetic", "schedtest", false); trace_put_event_file(schedtest_event_file); If those have been successful, synth_event_delete() can be called to -remove the event: +remove the event:: ret = synth_event_delete("schedtest"); -6.3.3.1 Tracing a synthetic event piecewise -------------------------------------------- +7.2.2 Tracing a synthetic event piecewise +----------------------------------------- To trace a synthetic using the piecewise method described above, the synth_event_trace_start() function is used to 'open' the synthetic -event trace: +event trace:: - struct synth_trace_state trace_state; + struct synth_event_trace_state trace_state; ret = synth_event_trace_start(schedtest_event_file, &trace_state); It's passed the trace_event_file representing the synthetic event using the same methods as described above, along with a pointer to a -struct synth_trace_state object, which will be zeroed before use and +struct synth_event_trace_state object, which will be zeroed before use and used to maintain state between this and following calls. Once the event has been opened, which means space for it has been @@ -804,12 +835,12 @@ lookup per field. To assign the values one after the other without lookups, synth_event_add_next_val() should be used. Each call is passed the -same synth_trace_state object used in the synth_event_trace_start(), +same synth_event_trace_state object used in the synth_event_trace_start(), along with the value to set the next field in the event. After each field is set, the 'cursor' points to the next field, which will be set by the subsequent call, continuing until all the fields have been set in order. The same sequence of calls as in the above examples using -this method would be (without error-handling code): +this method would be (without error-handling code):: /* next_pid_field */ ret = synth_event_add_next_val(777, &trace_state); @@ -833,11 +864,11 @@ this method would be (without error-handling code): ret = synth_event_add_next_val(395, &trace_state); To assign the values in any order, synth_event_add_val() should be -used. Each call is passed the same synth_trace_state object used in +used. Each call is passed the same synth_event_trace_state object used in the synth_event_trace_start(), along with the field name of the field to set and the value to set it to. The same sequence of calls as in the above examples using this method would be (without error-handling -code): +code):: ret = synth_event_add_val("next_pid_field", 777, &trace_state); ret = synth_event_add_val("next_comm_field", (u64)"silly putty", @@ -855,7 +886,7 @@ can be used but not both at the same time. Finally, the event won't be actually traced until it's 'closed', which is done using synth_event_trace_end(), which takes only the -struct synth_trace_state object used in the previous calls: +struct synth_event_trace_state object used in the previous calls:: ret = synth_event_trace_end(&trace_state); @@ -863,8 +894,8 @@ Note that synth_event_trace_end() must be called at the end regardless of whether any of the add calls failed (say due to a bad field name being passed in). -6.3.4 Dyamically creating kprobe and kretprobe event definitions ----------------------------------------------------------------- +7.3 Dyamically creating kprobe and kretprobe event definitions +-------------------------------------------------------------- To create a kprobe or kretprobe trace event from kernel code, the kprobe_event_gen_cmd_start() or kretprobe_event_gen_cmd_start() @@ -878,7 +909,7 @@ function. Before calling kprobe_event_gen_cmd_start(), the user should create and initialize a dynevent_cmd object using kprobe_event_cmd_init(). -For example, to create a new "schedtest" kprobe event with two fields: +For example, to create a new "schedtest" kprobe event with two fields:: struct dynevent_cmd cmd; char *buf; @@ -900,18 +931,18 @@ Once the kprobe event object has been created, it can then be populated with more fields. Fields can be added using kprobe_event_add_fields(), supplying the dynevent_cmd object along with a variable arg list of probe fields. For example, to add a -couple additional fields, the following call could be made: +couple additional fields, the following call could be made:: ret = kprobe_event_add_fields(&cmd, "flags=%cx", "mode=+4($stack)"); Once all the fields have been added, the event should be finalized and registered by calling the kprobe_event_gen_cmd_end() or kretprobe_event_gen_cmd_end() functions, depending on whether a kprobe -or kretprobe command was started: +or kretprobe command was started:: ret = kprobe_event_gen_cmd_end(&cmd); -or +or:: ret = kretprobe_event_gen_cmd_end(&cmd); @@ -920,13 +951,13 @@ events. Similarly, a kretprobe event can be created using kretprobe_event_gen_cmd_start() with a probe name and location and -additional params such as $retval: +additional params such as $retval:: ret = kretprobe_event_gen_cmd_start(&cmd, "gen_kretprobe_test", "do_sys_open", "$retval"); Similar to the synthetic event case, code like the following can be -used to enable the newly created kprobe event: +used to enable the newly created kprobe event:: gen_kprobe_test = trace_get_event_file(NULL, "kprobes", "gen_kprobe_test"); @@ -934,14 +965,14 @@ used to enable the newly created kprobe event: "kprobes", "gen_kprobe_test", true); Finally, also similar to synthetic events, the following code can be -used to give the kprobe event file back and delete the event: +used to give the kprobe event file back and delete the event:: trace_put_event_file(gen_kprobe_test); ret = kprobe_event_delete("gen_kprobe_test"); -6.3.4 The "dynevent_cmd" low-level API --------------------------------------- +7.4 The "dynevent_cmd" low-level API +------------------------------------ Both the in-kernel synthetic event and kprobe interfaces are built on top of a lower-level "dynevent_cmd" interface. This interface is @@ -963,7 +994,7 @@ are described below. The first step in building a new command string is to create and initialize an instance of a dynevent_cmd. Here, for instance, we -create a dynevent_cmd on the stack and initialize it: +create a dynevent_cmd on the stack and initialize it:: struct dynevent_cmd cmd; char *buf; @@ -989,7 +1020,7 @@ calls to argument-adding functions. To add a single argument, define and initialize a struct dynevent_arg or struct dynevent_arg_pair object. Here's an example of the simplest possible arg addition, which is simply to append the given string as -a whitespace-separated argument to the command: +a whitespace-separated argument to the command:: struct dynevent_arg arg; @@ -1007,7 +1038,7 @@ the arg. Here's another more complicated example using an 'arg pair', which is used to create an argument that consists of a couple components added together as a unit, for example, a 'type field_name;' arg or a simple -expression arg e.g. 'flags=%cx': +expression arg e.g. 'flags=%cx':: struct dynevent_arg_pair arg_pair; @@ -1031,7 +1062,7 @@ Any number of dynevent_*_add() calls can be made to build up the string (until its length surpasses cmd->maxlen). When all the arguments have been added and the command string is complete, the only thing left to do is run the command, which happens by simply calling -dynevent_create(): +dynevent_create():: ret = dynevent_create(&cmd); |