From 889204278ccf98c5c097b1d1ae69babc6a3222fd Mon Sep 17 00:00:00 2001 From: "Steven Rostedt (Red Hat)" Date: Wed, 1 Apr 2015 14:57:27 -0400 Subject: tracing: Update trace-event-sample with TRACE_SYSTEM_VAR documentation Add documentation about TRACE_SYSTEM needing to be alpha-numeric or with underscores, and that if it is not, then the use of TRACE_SYSTEM_VAR is required to make something that is. An example of this is shown in samples/trace_events/trace-events-sample.h Link: http://lkml.kernel.org/r/20150403013802.220157513@goodmis.org Reviewed-by: Masami Hiramatsu Tested-by: Masami Hiramatsu Signed-off-by: Steven Rostedt --- samples/trace_events/trace-events-sample.h | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'samples') diff --git a/samples/trace_events/trace-events-sample.h b/samples/trace_events/trace-events-sample.h index a2c8b02b6359..19405f18cc8a 100644 --- a/samples/trace_events/trace-events-sample.h +++ b/samples/trace_events/trace-events-sample.h @@ -22,7 +22,25 @@ * protection, just like TRACE_INCLUDE_FILE. */ #undef TRACE_SYSTEM -#define TRACE_SYSTEM sample +#define TRACE_SYSTEM sample-trace + +/* + * TRACE_SYSTEM is expected to be a C valid variable (alpha-numeric + * and underscore), although it may start with numbers. If for some + * reason it is not, you need to add the following lines: + */ +#undef TRACE_SYSTEM_VAR +#define TRACE_SYSTEM_VAR sample_trace +/* + * But the above is only needed if TRACE_SYSTEM is not alpha-numeric + * and underscored. By default, TRACE_SYSTEM_VAR will be equal to + * TRACE_SYSTEM. As TRACE_SYSTEM_VAR must be alpha-numeric, if + * TRACE_SYSTEM is not, then TRACE_SYSTEM_VAR must be defined with + * only alpha-numeric and underscores. + * + * The TRACE_SYSTEM_VAR is only used internally and not visible to + * user space. + */ /* * Notice that this file is not protected like a normal header. -- cgit v1.2.3 From 32eb3d0d09943ab9dcc01fb8d2619b64e965992c Mon Sep 17 00:00:00 2001 From: "Steven Rostedt (Red Hat)" Date: Wed, 1 Apr 2015 15:55:36 -0400 Subject: tracing/samples: Update the trace-event-sample.h with TRACE_DEFINE_ENUM() Document the use of TRACE_DEFINE_ENUM() by adding enums to the trace-event-sample.h and using this macro to convert them in the format files. Also update the comments and sho the use of __print_symbolic() and __print_flags() as well as adding comments abount __print_array(). Link: http://lkml.kernel.org/r/20150403013802.220157513@goodmis.org Reviewed-by: Masami Hiramatsu Tested-by: Masami Hiramatsu Signed-off-by: Steven Rostedt --- samples/trace_events/trace-events-sample.h | 64 +++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) (limited to 'samples') diff --git a/samples/trace_events/trace-events-sample.h b/samples/trace_events/trace-events-sample.h index 19405f18cc8a..8965d1bb8811 100644 --- a/samples/trace_events/trace-events-sample.h +++ b/samples/trace_events/trace-events-sample.h @@ -198,8 +198,30 @@ static inline int __length_of(const int *list) ; return i; } + +enum { + TRACE_SAMPLE_FOO = 2, + TRACE_SAMPLE_BAR = 4, + TRACE_SAMPLE_ZOO = 8, +}; #endif +/* + * If enums are used in the TP_printk(), their names will be shown in + * format files and not their values. This can cause problems with user + * space programs that parse the format files to know how to translate + * the raw binary trace output into human readable text. + * + * To help out user space programs, any enum that is used in the TP_printk() + * should be defined by TRACE_DEFINE_ENUM() macro. All that is needed to + * be done is to add this macro with the enum within it in the trace + * header file, and it will be converted in the output. + */ + +TRACE_DEFINE_ENUM(TRACE_SAMPLE_FOO); +TRACE_DEFINE_ENUM(TRACE_SAMPLE_BAR); +TRACE_DEFINE_ENUM(TRACE_SAMPLE_ZOO); + TRACE_EVENT(foo_bar, TP_PROTO(const char *foo, int bar, const int *lst, @@ -224,7 +246,47 @@ TRACE_EVENT(foo_bar, __assign_bitmask(cpus, cpumask_bits(mask), num_possible_cpus()); ), - TP_printk("foo %s %d %s %s (%s)", __entry->foo, __entry->bar, + TP_printk("foo %s %d %s %s %s %s (%s)", __entry->foo, __entry->bar, + +/* + * Notice here the use of some helper functions. This includes: + * + * __print_symbolic( variable, { value, "string" }, ... ), + * + * The variable is tested against each value of the { } pair. If + * the variable matches one of the values, then it will print the + * string in that pair. If non are matched, it returns a string + * version of the number (if __entry->bar == 7 then "7" is returned). + */ + __print_symbolic(__entry->bar, + { 0, "zero" }, + { TRACE_SAMPLE_FOO, "TWO" }, + { TRACE_SAMPLE_BAR, "FOUR" }, + { TRACE_SAMPLE_ZOO, "EIGHT" }, + { 10, "TEN" } + ), + +/* + * __print_flags( variable, "delim", { value, "flag" }, ... ), + * + * This is similar to __print_symbolic, except that it tests the bits + * of the value. If ((FLAG & variable) == FLAG) then the string is + * printed. If more than one flag matches, then each one that does is + * also printed with delim in between them. + * If not all bits are accounted for, then the not found bits will be + * added in hex format: 0x506 will show BIT2|BIT4|0x500 + */ + __print_flags(__entry->bar, "|", + { 1, "BIT1" }, + { 2, "BIT2" }, + { 4, "BIT3" }, + { 8, "BIT4" } + ), +/* + * __print_array( array, len, element_size ) + * + * This prints out the array that is defined by __array in a nice format. + */ __print_array(__get_dynamic_array(list), __get_dynamic_array_len(list), sizeof(int)), -- cgit v1.2.3