Re: [PATCH v5 17/30] tools/lib/traceevent: Man pages for libtraceevent event print related APIs

[Steven Rostedt <rostedt@goodmis.org>]

On Fri, 12 Apr 2019 16:37:58 +0300
Tzvetomir Stoyanov <tstoyanov@vmware.com> 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@vmware.com>
> ---
>  .../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@goodmis.org>, author of *libtraceevent*.
> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to  <linux-trace-devel@vger.kernel.org>
> +
> +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