On Fri, 12 Apr 2019 16:37:58 +0300
Tzvetomir Stoyanov <tstoyanov@xxxxxxxxxx> wrote:
> Added new man pages, describing libtraceevent event print related APIs:
> tep_print_event(),
> tep_print_event_data(),
> tep_event_info(),
> tep_print_event_task(),
> tep_print_event_time(),
> tep_set_print_raw()
Yeah, here's another set that needs to change.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@xxxxxxxxxx>
> ---
> .../libtraceevent-event_print.txt | 138 ++++++++++++++++++
> 1 file changed, 138 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
> new file mode 100644
> index 000000000000..2a0dec71fd99
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
> @@ -0,0 +1,138 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_print_event, tep_print_event_data, tep_event_info, tep_print_event_task,
> +tep_print_event_time, tep_set_print_raw - Parses the data into the print format.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +*#include <trace-seq.h>*
> +
> +void *tep_print_event_time*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]record, bool _use_trace_clock_);
The "use_trace_clock" needs to go. It's probably best to pass in a
precision and divisor.
tep_print_event_time(tep, &seq, event, record, precision, divisor)
For a counter we would just have:
0, 0)
For full nsecs:
9, 0)
For usecs:
6, 1000)
Where we would take the number and do:
long long divisors[] = {
1, 10, 100, 1000, 10000, 100000, 1000000,
10000000, 100000000, 1000000000, 10000000000 }
ts = record->ts;
if (divisor)
ts /= divisor;
if (precision) {
if (precision > (sizeof(divisors) / sizeof(divisors[0])) {
warn();
last = ts;
} else {
first = ts / divisors[precision];
last = ts - first * divisors[precision];
}
trace_seq_printf(seq, " %5lu.%0*lu", first, precision, last);
} else
trace_seq_printf(seq, " %12lu", ts);
something like that.
> +void *tep_print_event_task*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_);
> +void *tep_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_);
> +void *tep_print_event_data*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_);
> +void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, bool _use_trace_clock_);
> +void *tep_set_print_raw*(struct tep_handle pass:[*]_tep_, int _print_raw_);
I'm also thinking of modifying all of these to be the bare minimum of
what they do, and have the callers do the rest.
Let's hold off on these man pages. I think we are going to rewrite a
lot of this code first.
-- Steve
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_print_event_time()_ function writes the timestamp of the given _record_
> +into the trace sequence _s_. The _tep_ argument is trace event parser context.
> +The _use_trace_clock_ argument indicates if the tep->trace_clock should be used
> +for parsing the timestamp.
> +
> +The _tep_print_event_task()_ function writes the task command, pid and CPU of
> +the given _record_ using the given _event_ information into the trace sequence
> +_s_. The _tep_ argument is trace event parser context.
> +
> +The _tep_event_info()_ function parses the raw data from the _record_ using
> +the given _event_ information and writes the print format into the trace
> +sequence _s_.
> +
> +The _tep_print_event_data()_ function writes the name of the _record_ using the
> +given _event_ information into the trace sequence _s_ and calls
> +_tep_event_info()_ to parse and write the raw data from the _record_. The _tep_
> +argument is trace event parser context.
> +
> +The _tep_print_event()_ function writes the _record_ information. It finds the
> +corresponding event and calls _tep_print_event_task()_, _tep_print_event_time()_
> +and _tep_print_event_data()_ to parse and write the information, into the trace
> +sequence _s_. The _tep_ argument is trace event parser context.
> +The _use_trace_clock_ argument indicates if the tep->trace_clock should be used
> +for parsing the timestamp.
> +
> +The _tep_set_print_raw()_ function forces event's information to be printed in
> +raw format. It changes the behavior of _tep_event_info()_ function. The _tep_
> +argument is trace event parser context. The _print_raw_ argument specifies
> +whether to print in raw format or not.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +#include <trace-seq.h>
> +...
> +struct trace_seq seq;
> +trace_seq_init(&seq);
> +struct tep_handle *tep = tep_alloc();
> +...
> +void print_my_event(struct tep_record *record)
> +{
> + struct tep_event *event;
> +
> + /* print all event information */
> + trace_seq_reset(&seq);
> + tep_print_event(tep, &seq, record, TRUE);
> +
> + event = tep_find_event_by_record(tep, record);
> +
> + if (event != NULL) {
> + /* print event timestamp */
> + trace_seq_reset(&seq);
> + tep_print_event_time(tep, &seq, event, record, TRUE);
> +
> + /* print event task information */
> + trace_seq_reset(&seq);
> + tep_print_event_task(tep, &seq, event, record);
> +
> + /* print event name and raw data */
> + trace_seq_reset(&seq);
> + tep_print_event_data(tep, &seq, event, record);
> +
> + /* print event raw data */
> + trace_seq_reset(&seq);
> + tep_event_info(&seq, event, record);
> +
> + /* print event raw data in raw format */
> + trace_seq_reset(&seq);
> + tep_set_print_raw(tep, 1);
> + tep_event_info(&seq, event, record);
> + }
> +}
> +...
> +--
> +
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> + Header file to include in order to have access to the library APIs.
> +*trace-seq.h*
> + Header file to include in order to have access to trace sequences related APIs.
> + Trace sequences are used to allow a function to call several other functions
> + to create a string of data to use.
> +*-ltraceevent*
> + Linker switch to add when building a program that uses the library.
> +--
> +
> +SEE ALSO
> +--------
> +_libtraceevent(3)_, _trace-cmd(1)_
> +
> +AUTHOR
> +------
> +[verse]
> +--
> +*Steven Rostedt* <rostedt@xxxxxxxxxxx>, author of *libtraceevent*.
> +*Tzvetomir Stoyanov* <tz.stoyanov@xxxxxxxxx>, author of this man page.
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx>
> +
> +LICENSE
> +-------
> +libtraceevent is Free Software licensed under the GNU LGPL 2.1
> +
> +RESOURCES
> +---------
> +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|