* [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-18 21:04 ` [Suspected Spam] " Matt Helsley
2019-03-08 13:36 ` [PATCH v4 02/46] tools/lib/traceevent: Fix libtraceevent/Documentation Makefile Tzvetomir Stoyanov
` (45 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
This patch adds initial support for libtraceevent man pages -
Documentation directory, templates, configurations, Makefiles.
The first man page is also part of the patch - summary of the
library and all its APIs. Building of the documentation is
integrated into the libtraceevent build process, new targets are
added to its Makefile:
make doc
make doc-clean
make doc-install
make doc-uninstall
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++
.../traceevent/Documentation/asciidoc.conf | 91 ++++++++
.../Documentation/libtraceevent.txt | 198 +++++++++++++++++
.../traceevent/Documentation/manpage-1.72.xsl | 14 ++
.../traceevent/Documentation/manpage-base.xsl | 35 +++
.../Documentation/manpage-bold-literal.xsl | 17 ++
.../Documentation/manpage-normal.xsl | 13 ++
.../Documentation/manpage-suppress-sp.xsl | 21 ++
tools/lib/traceevent/Makefile | 13 ++
9 files changed, 607 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/Makefile
create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
diff --git a/tools/lib/traceevent/Documentation/Makefile b/tools/lib/traceevent/Documentation/Makefile
new file mode 100644
index 000000000000..e17c0723b4e1
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/Makefile
@@ -0,0 +1,205 @@
+include ../../../scripts/Makefile.include
+include ../../../scripts/utilities.mak
+
+MAN3_TXT= \
+ $(wildcard libtraceevent-*.txt) \
+ libtraceevent.txt
+
+MAN_TXT = $(MAN3_TXT)
+_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
+_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
+_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT))
+
+MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML))
+MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML))
+DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3))
+
+# Make the path relative to DESTDIR, not prefix
+ifndef DESTDIR
+prefix?=$(HOME)
+endif
+bindir?=$(prefix)/bin
+htmldir?=$(prefix)/share/doc/libtraceevent-doc
+pdfdir?=$(prefix)/share/doc/libtraceevent-doc
+mandir?=$(prefix)/share/man
+man3dir=$(mandir)/man3
+
+ASCIIDOC=asciidoc
+ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf
+ASCIIDOC_HTML = xhtml11
+MANPAGE_XSL = manpage-normal.xsl
+XMLTO_EXTRA =
+INSTALL?=install
+RM ?= rm -f
+
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_EXTRA = -a compat-mode
+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
+ASCIIDOC_EXTRA += -a mansource="libtraceevent" -a manmanual="libtraceevent Manual"
+ASCIIDOC_HTML = xhtml5
+endif
+
+XMLTO=xmlto
+
+_tmp_tool_path := $(call get-executable,$(ASCIIDOC))
+ifeq ($(_tmp_tool_path),)
+ missing_tools = $(ASCIIDOC)
+endif
+
+ifndef USE_ASCIIDOCTOR
+_tmp_tool_path := $(call get-executable,$(XMLTO))
+ifeq ($(_tmp_tool_path),)
+ missing_tools += $(XMLTO)
+endif
+endif
+
+#
+# For asciidoc ...
+# -7.1.2, no extra settings are needed.
+# 8.0-, set ASCIIDOC8.
+#
+
+#
+# For docbook-xsl ...
+# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
+# 1.69.0, no extra settings are needed?
+# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP?
+# 1.71.1, no extra settings are needed?
+# 1.72.0, set DOCBOOK_XSL_172.
+# 1.73.0-, set ASCIIDOC_NO_ROFF
+#
+
+#
+# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
+# of 'the ".ft C" problem' in your generated manpages, and you
+# instead ended up with weird characters around callouts, try
+# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
+#
+
+ifdef ASCIIDOC8
+ASCIIDOC_EXTRA += -a asciidoc7compatible
+endif
+ifdef DOCBOOK_XSL_172
+ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff
+MANPAGE_XSL = manpage-1.72.xsl
+else
+ ifdef ASCIIDOC_NO_ROFF
+ # docbook-xsl after 1.72 needs the regular XSL, but will not
+ # pass-thru raw roff codes from asciidoc.conf, so turn them off.
+ ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff
+ endif
+endif
+ifdef MAN_BOLD_LITERAL
+XMLTO_EXTRA += -m manpage-bold-literal.xsl
+endif
+ifdef DOCBOOK_SUPPRESS_SP
+XMLTO_EXTRA += -m manpage-suppress-sp.xsl
+endif
+
+SHELL_PATH ?= $(SHELL)
+# Shell quote;
+SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
+
+DESTDIR ?=
+DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))'
+
+export DESTDIR DESTDIR_SQ
+
+#
+# Please note that there is a minor bug in asciidoc.
+# The version after 6.0.3 _will_ include the patch found here:
+# http://marc.theaimsgroup.com/?l=libtraceevent&m=111558757202243&w=2
+#
+# Until that version is released you may have to apply the patch
+# yourself - yes, all 6 characters of it!
+#
+QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir
+QUIET_SUBDIR1 =
+
+ifneq ($(findstring $(MAKEFLAGS),w),w)
+PRINT_DIR = --no-print-directory
+else # "make -w"
+NO_SUBDIR = :
+endif
+
+ifneq ($(findstring $(MAKEFLAGS),s),s)
+ifneq ($(V),1)
+ QUIET_ASCIIDOC = @echo ' ASCIIDOC '$@;
+ QUIET_XMLTO = @echo ' XMLTO '$@;
+ QUIET_SUBDIR0 = +@subdir=
+ QUIET_SUBDIR1 = ;$(NO_SUBDIR) \
+ echo ' SUBDIR ' $$subdir; \
+ $(MAKE) $(PRINT_DIR) -C $$subdir
+ export V
+endif
+endif
+
+all: html man
+
+man: man3
+man3: $(DOC_MAN3)
+
+html: $(MAN_HTML)
+
+$(MAN_HTML) $(DOC_MAN3): asciidoc.conf
+
+install: install-man
+
+check-man-tools:
+ifdef missing_tools
+ $(error "You need to install $(missing_tools) for man pages")
+endif
+
+do-install-man: man
+ $(call QUIET_INSTALL, Documentation-man) \
+ $(INSTALL) -d -m 755 $(DESTDIR)$(man3dir); \
+ $(INSTALL) -m 644 $(DOC_MAN3) $(DESTDIR)$(man3dir);
+
+install-man: check-man-tools man do-install-man
+
+uninstall: uninstall-man
+
+uninstall-man:
+ $(call QUIET_UNINST, Documentation-man) \
+ $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3))
+
+
+ifdef missing_tools
+ DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed)
+else
+ DO_INSTALL_MAN = do-install-man
+endif
+
+CLEAN_FILES = \
+ $(MAN_XML) $(addsuffix +,$(MAN_XML)) \
+ $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \
+ $(DOC_MAN3)
+
+clean:
+ $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES)
+
+ifdef USE_ASCIIDOCTOR
+$(OUTPUT)%.3 : $(OUTPUT)%.txt
+ $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+ $(ASCIIDOC) -b manpage -d manpage \
+ $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \
+ mv $@+ $@
+endif
+
+$(OUTPUT)%.3 : $(OUTPUT)%.xml
+ $(QUIET_XMLTO)$(RM) $@ && \
+ $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+$(OUTPUT)%.xml : %.txt
+ $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+ $(ASCIIDOC) -b docbook -d manpage \
+ $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \
+ mv $@+ $@
+
+$(MAN_HTML): $(OUTPUT)%.html : %.txt
+ $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+ $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \
+ $(ASCIIDOC_EXTRA) -aperf_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \
+ mv $@+ $@
+
diff --git a/tools/lib/traceevent/Documentation/asciidoc.conf b/tools/lib/traceevent/Documentation/asciidoc.conf
new file mode 100644
index 000000000000..1b03c63fb73a
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/asciidoc.conf
@@ -0,0 +1,91 @@
+## linktep: macro
+#
+# Usage: linktep:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show TEP link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linktep):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[attributes]
+asterisk=*
+plus=+
+caret=^
+startsb=[
+endsb=]
+tilde=~
+
+ifdef::backend-docbook[]
+[linktep-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+ifndef::tep-asciidoc-no-roff[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+# v1.72 breaks with this because it replaces dots not in roff requests.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+ifdef::doctype-manpage[]
+ .ft C
+endif::doctype-manpage[]
+|
+ifdef::doctype-manpage[]
+ .ft
+endif::doctype-manpage[]
+</literallayout>
+{title#}</example>
+endif::tep-asciidoc-no-roff[]
+
+ifdef::tep-asciidoc-no-roff[]
+ifdef::doctype-manpage[]
+# The following two small workarounds insert a simple paragraph after screen
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout><simpara></simpara>
+{title#}</example>
+
+[verseblock]
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+{title#}<literallayout>
+|
+</literallayout>
+{title#}</para></formalpara>
+{title%}<simpara></simpara>
+endif::doctype-manpage[]
+endif::tep-asciidoc-no-roff[]
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">trace-cmd</refmiscinfo>
+<refmiscinfo class="version">{libtraceevent_version}</refmiscinfo>
+<refmiscinfo class="manual">trace-cmd Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[linktep-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
diff --git a/tools/lib/traceevent/Documentation/libtraceevent.txt b/tools/lib/traceevent/Documentation/libtraceevent.txt
new file mode 100644
index 000000000000..14125261661c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent.txt
@@ -0,0 +1,198 @@
+libtraceevent(3)
+================
+
+NAME
+----
+libtraceevent - Linux kernel trace event library
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+Management of tep handler data structure and access of its members:
+ struct tep_handle pass:[*]*tep_alloc*(void);
+ void *tep_free*(struct tep_handle pass:[*]_tep_);
+ void *tep_ref*(struct tep_handle pass:[*]_tep_);
+ void *tep_unref*(struct tep_handle pass:[*]_tep_);
+ int *tep_ref_get*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_flag*(struct tep_handle pass:[*]_tep_, int _flag_);
+ int *tep_get_cpus*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_);
+ int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_);
+ void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_);
+ int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
+ int *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
+ int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_);
+ int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_);
+
+Register / unregister APIs:
+ int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_);
+ int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
+ int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_);
+ int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_);
+ int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
+ int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
+ int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
+
+Plugins management:
+ struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_);
+ void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_);
+ char pass:[*]pass:[*]*tep_plugin_list_options*(void);
+ void *tep_plugin_free_options_list*(char pass:[*]pass:[*]_list_);
+ int *tep_plugin_add_options*(const char pass:[*]_name_, struct tep_plugin_option pass:[*]_options_);
+ void *tep_plugin_remove_options*(struct tep_plugin_option pass:[*]_options_);
+ void *tep_print_plugins*(struct trace_seq pass:[*]_s_, const char pass:[*]_prefix_, const char pass:[*]_suffix_, const struct tep_plugin_list pass:[*]_list_);
+
+Event related APIs:
+ struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_);
+ int *tep_get_events_count*(struct tep_handle pass:[*]_tep_);
+ struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
+
+Event printing:
+ 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_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_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_);
+ 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_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_);
+
+Event finding:
+ struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_);
+ struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_);
+ struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_);
+
+Parsing of event files:
+ int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_);
+ enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);
+ enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);
+
+APIs related to fields from event's format files:
+ struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_);
+ struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_);
+ void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_);
+ int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+ int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+ int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+ int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_);
+
+Event fileds printing:
+ void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_);
+ void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_);
+ int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
+ int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
+
+Event fileds finding:
+ struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+ struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
+ struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+
+Functions resolver:
+ int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
+ void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
+ const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
+ unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
+
+Filter management:
+ struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
+ enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
+ enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
+ int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
+ int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+ void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
+ int *tep_filter_clear_trivial*(struct tep_event_filter pass:[*]_filter_, enum tep_filter_trivial_type _type_);
+ void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
+ char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+ int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+ int *tep_filter_event_has_trivial*(struct tep_event_filter pass:[*]_filter_, int _event_id_, enum tep_filter_trivial_type _type_);
+ int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
+ int *tep_update_trivial*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_, enum tep_filter_trivial_type _type_);
+ int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
+
+Parsing various data from the records:
+ void *tep_data_lat_fmt*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
+ int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+ int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+ int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+ int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+
+Command and task related APIs:
+ const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_tep_, int _pid_);
+ struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_);
+ int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
+ int *tep_pid_is_registered*(struct tep_handle pass:[*]_tep_, int _pid_);
+ int *tep_cmdline_pid*(struct tep_handle pass:[*]_tep_, struct cmdline pass:[*]_cmdline_);
+
+Endian related APIs:
+ int *tep_host_bigendian*(void);
+ unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_);
+ int *tep_file_bigendian*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+ int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_);
+ void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+
+Trace sequences:
+*#include <trace-seq.h>*
+ void *trace_seq_init*(struct trace_seq pass:[*]_s_);
+ void *trace_seq_reset*(struct trace_seq pass:[*]_s_);
+ void *trace_seq_destroy*(struct trace_seq pass:[*]_s_);
+ int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, ...);
+ int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_);
+ int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_);
+ int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_);
+ void *trace_seq_terminate*(struct trace_seq pass:[*]_s_);
+ int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_);
+ int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_);
+--
+
+DESCRIPTION
+-----------
+The libtraceevent(3) library provides APIs to access kernel tracepoint events,
+located in the debugfs file system under the tracing/events directory.
+
+ENVIRONMENT
+-----------
+[verse]
+--
+TRACEEVENT_PLUGIN_DIR
+ Additional plugin directory. All shared object files, located in this directory will be loaded as traceevent plugins.
+--
+
+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
+--------
+_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
diff --git a/tools/lib/traceevent/Documentation/manpage-1.72.xsl b/tools/lib/traceevent/Documentation/manpage-1.72.xsl
new file mode 100644
index 000000000000..b4d315cb8c47
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/manpage-1.72.xsl
@@ -0,0 +1,14 @@
+<!-- manpage-1.72.xsl:
+ special settings for manpages rendered from asciidoc+docbook
+ handles peculiarities in docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the special values for the roff control characters
+ needed for docbook-xsl 1.72.0 -->
+<xsl:param name="git.docbook.backslash">▓</xsl:param>
+<xsl:param name="git.docbook.dot" >⌂</xsl:param>
+
+</xsl:stylesheet>
diff --git a/tools/lib/traceevent/Documentation/manpage-base.xsl b/tools/lib/traceevent/Documentation/manpage-base.xsl
new file mode 100644
index 000000000000..a264fa616093
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/manpage-base.xsl
@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+ special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format;
+ git.docbook.backslash and git.docbook.dot params
+ must be supplied by another XSL file or other means -->
+<xsl:template match="co">
+ <xsl:value-of select="concat(
+ $git.docbook.backslash,'fB(',
+ substring-after(@id,'-'),')',
+ $git.docbook.backslash,'fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+ <xsl:value-of select="$git.docbook.dot"/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+ <xsl:value-of select="concat(
+ $git.docbook.backslash,'fB',
+ substring-after(@arearefs,'-'),
+ '. ',$git.docbook.backslash,'fR')"/>
+ <xsl:apply-templates/>
+ <xsl:value-of select="$git.docbook.dot"/>
+ <xsl:text>br </xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl b/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 000000000000..608eb5df6281
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
@@ -0,0 +1,17 @@
+<!-- manpage-bold-literal.xsl:
+ special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<!-- render literal text as bold (instead of plain or monospace);
+ this makes literal text easier to distinguish in manpages
+ viewed on a tty -->
+<xsl:template match="literal">
+ <xsl:value-of select="$git.docbook.backslash"/>
+ <xsl:text>fB</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:value-of select="$git.docbook.backslash"/>
+ <xsl:text>fR</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/tools/lib/traceevent/Documentation/manpage-normal.xsl b/tools/lib/traceevent/Documentation/manpage-normal.xsl
new file mode 100644
index 000000000000..a48f5b11f3dc
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/manpage-normal.xsl
@@ -0,0 +1,13 @@
+<!-- manpage-normal.xsl:
+ special settings for manpages rendered from asciidoc+docbook
+ handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot" >.</xsl:param>
+
+</xsl:stylesheet>
diff --git a/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl b/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
new file mode 100644
index 000000000000..a63c7632a87d
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
@@ -0,0 +1,21 @@
+<!-- manpage-suppress-sp.xsl:
+ special settings for manpages rendered from asciidoc+docbook
+ handles erroneous, inline .sp in manpage output of some
+ versions of docbook-xsl -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<!-- attempt to work around spurious .sp at the tail of the line
+ that some versions of docbook stylesheets seem to add -->
+<xsl:template match="simpara">
+ <xsl:variable name="content">
+ <xsl:apply-templates/>
+ </xsl:variable>
+ <xsl:value-of select="normalize-space($content)"/>
+ <xsl:if test="not(ancestor::authorblurb) and
+ not(ancestor::personblurb)">
+ <xsl:text> </xsl:text>
+ </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/tools/lib/traceevent/Makefile b/tools/lib/traceevent/Makefile
index f65243137d6d..3764e003d1cc 100644
--- a/tools/lib/traceevent/Makefile
+++ b/tools/lib/traceevent/Makefile
@@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \
export man_dir man_dir_SQ INSTALL
export DESTDIR DESTDIR_SQ
+export EVENT_PARSE_VERSION
set_plugin_dir := 1
@@ -313,6 +314,18 @@ clean:
$(RM) TRACEEVENT-CFLAGS tags TAGS; \
$(RM) $(PKG_CONFIG_FILE)
+doc:
+ $(call descend,Documentation)
+
+doc-clean:
+ $(call descend,Documentation,clean)
+
+doc-install:
+ $(call descend,Documentation,install)
+
+doc-uninstall:
+ $(call descend,Documentation,uninstall)
+
PHONY += force plugins
force:
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [Suspected Spam] [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages
2019-03-08 13:36 ` [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages Tzvetomir Stoyanov
@ 2019-03-18 21:04 ` Matt Helsley
2019-03-19 11:28 ` Tzvetomir Stoyanov
0 siblings, 1 reply; 80+ messages in thread
From: Matt Helsley @ 2019-03-18 21:04 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: rostedt, linux-trace-devel
> On Mar 8, 2019, at 5:36 AM, Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> This patch adds initial support for libtraceevent man pages -
> Documentation directory, templates, configurations, Makefiles.
> The first man page is also part of the patch - summary of the
> library and all its APIs. Building of the documentation is
> integrated into the libtraceevent build process, new targets are
> added to its Makefile:
> make doc
> make doc-clean
> make doc-install
> make doc-uninstall
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++
> .../traceevent/Documentation/asciidoc.conf | 91 ++++++++
> .../Documentation/libtraceevent.txt | 198 +++++++++++++++++
> .../traceevent/Documentation/manpage-1.72.xsl | 14 ++
> .../traceevent/Documentation/manpage-base.xsl | 35 +++
> .../Documentation/manpage-bold-literal.xsl | 17 ++
> .../Documentation/manpage-normal.xsl | 13 ++
> .../Documentation/manpage-suppress-sp.xsl | 21 ++
> tools/lib/traceevent/Makefile | 13 ++
> 9 files changed, 607 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/Makefile
> create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
> create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
> <snip>
> diff --git a/tools/lib/traceevent/Makefile b/tools/lib/traceevent/Makefile
> index f65243137d6d..3764e003d1cc 100644
> --- a/tools/lib/traceevent/Makefile
> +++ b/tools/lib/traceevent/Makefile
> @@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \
>
> export man_dir man_dir_SQ INSTALL
> export DESTDIR DESTDIR_SQ
> +export EVENT_PARSE_VERSION
>
> set_plugin_dir := 1
>
> @@ -313,6 +314,18 @@ clean:
> $(RM) TRACEEVENT-CFLAGS tags TAGS; \
> $(RM) $(PKG_CONFIG_FILE)
>
nit: I notice you’re adding new targets which should probably be added to PHONY. e.g.:
PHONY += doc
> +doc:
> + $(call descend,Documentation)
> +
PHONY += doc-clean
> +doc-clean:
> + $(call descend,Documentation,clean)
> +
PHONY += doc-install
> +doc-install:
> + $(call descend,Documentation,install)
> +
> +doc-uninstall:
> + $(call descend,Documentation,uninstall)
> +
Reviewed-by: Matt Helsley <mhelsley@vmware.com>
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [Suspected Spam] [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages
2019-03-18 21:04 ` [Suspected Spam] " Matt Helsley
@ 2019-03-19 11:28 ` Tzvetomir Stoyanov
0 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-19 11:28 UTC (permalink / raw)
To: Matt Helsley; +Cc: rostedt, linux-trace-devel
On Mon, Mar 18, 2019 at 11:04 PM Matt Helsley <mhelsley@vmware.com> wrote:
>
>
>
> > On Mar 8, 2019, at 5:36 AM, Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> >
> > This patch adds initial support for libtraceevent man pages -
> > Documentation directory, templates, configurations, Makefiles.
> > The first man page is also part of the patch - summary of the
> > library and all its APIs. Building of the documentation is
> > integrated into the libtraceevent build process, new targets are
> > added to its Makefile:
> > make doc
> > make doc-clean
> > make doc-install
> > make doc-uninstall
> >
> > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> > ---
> > tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++
> > .../traceevent/Documentation/asciidoc.conf | 91 ++++++++
> > .../Documentation/libtraceevent.txt | 198 +++++++++++++++++
> > .../traceevent/Documentation/manpage-1.72.xsl | 14 ++
> > .../traceevent/Documentation/manpage-base.xsl | 35 +++
> > .../Documentation/manpage-bold-literal.xsl | 17 ++
> > .../Documentation/manpage-normal.xsl | 13 ++
> > .../Documentation/manpage-suppress-sp.xsl | 21 ++
> > tools/lib/traceevent/Makefile | 13 ++
> > 9 files changed, 607 insertions(+)
> > create mode 100644 tools/lib/traceevent/Documentation/Makefile
> > create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
>
>
> > <snip>
>
>
> > diff --git a/tools/lib/traceevent/Makefile b/tools/lib/traceevent/Makefile
> > index f65243137d6d..3764e003d1cc 100644
> > --- a/tools/lib/traceevent/Makefile
> > +++ b/tools/lib/traceevent/Makefile
> > @@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \
> >
> > export man_dir man_dir_SQ INSTALL
> > export DESTDIR DESTDIR_SQ
> > +export EVENT_PARSE_VERSION
> >
> > set_plugin_dir := 1
> >
> > @@ -313,6 +314,18 @@ clean:
> > $(RM) TRACEEVENT-CFLAGS tags TAGS; \
> > $(RM) $(PKG_CONFIG_FILE)
> >
> nit: I notice you’re adding new targets which should probably be added to PHONY. e.g.:
>
> PHONY += doc
> > +doc:
> > + $(call descend,Documentation)
> > +
>
> PHONY += doc-clean
> > +doc-clean:
> > + $(call descend,Documentation,clean)
> > +
>
> PHONY += doc-install
> > +doc-install:
> > + $(call descend,Documentation,install)
> > +
> > +doc-uninstall:
> > + $(call descend,Documentation,uninstall)
> > +
>
> Reviewed-by: Matt Helsley <mhelsley@vmware.com>
Thanks Matt, I'll add it in the next version of the patch.
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 02/46] tools/lib/traceevent: Fix libtraceevent/Documentation Makefile
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 03/46] tools/lib/traceevent: Add support for man pages with multiple names Tzvetomir Stoyanov
` (44 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
As libtraceevent/Documentation Makefile and all XLS files were taken
from tools/perf/Documentation, and modified for libtraceevent, this patch
adds a note on the top of the Makefile to state it. It also fixes the "clean"
rule, to clean up compiled man pages.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
tools/lib/traceevent/Documentation/Makefile | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/tools/lib/traceevent/Documentation/Makefile b/tools/lib/traceevent/Documentation/Makefile
index e17c0723b4e1..680a9771067f 100644
--- a/tools/lib/traceevent/Documentation/Makefile
+++ b/tools/lib/traceevent/Documentation/Makefile
@@ -1,6 +1,9 @@
include ../../../scripts/Makefile.include
include ../../../scripts/utilities.mak
+# This Makefile and manpage XSL files were taken from tools/perf/Documentation
+# and modified for libtraceevent.
+
MAN3_TXT= \
$(wildcard libtraceevent-*.txt) \
libtraceevent.txt
@@ -174,7 +177,7 @@ endif
CLEAN_FILES = \
$(MAN_XML) $(addsuffix +,$(MAN_XML)) \
$(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \
- $(DOC_MAN3)
+ $(DOC_MAN3) *.3
clean:
$(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES)
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 03/46] tools/lib/traceevent: Add support for man pages with multiple names
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 01/46] tools/lib/traceevent: Implement libtraceevent man pages Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 02/46] tools/lib/traceevent: Fix libtraceevent/Documentation Makefile Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 04/46] tools/lib/traceevent: libtraceevent Makefile "help" target Tzvetomir Stoyanov
` (43 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
This patch adds support for man pages with multiple names,
used to combine the description of several APIs into one page.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../traceevent/Documentation/asciidoc.conf | 35 +++++++++++++++++--
1 file changed, 32 insertions(+), 3 deletions(-)
diff --git a/tools/lib/traceevent/Documentation/asciidoc.conf b/tools/lib/traceevent/Documentation/asciidoc.conf
index 1b03c63fb73a..07595717f06e 100644
--- a/tools/lib/traceevent/Documentation/asciidoc.conf
+++ b/tools/lib/traceevent/Documentation/asciidoc.conf
@@ -74,12 +74,41 @@ template::[header-declarations]
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
-<refmiscinfo class="source">trace-cmd</refmiscinfo>
+<refmiscinfo class="source">libtraceevent</refmiscinfo>
<refmiscinfo class="version">{libtraceevent_version}</refmiscinfo>
-<refmiscinfo class="manual">trace-cmd Manual</refmiscinfo>
+<refmiscinfo class="manual">libtraceevent Manual</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>{manname}</refname>
+ <refname>{manname1}</refname>
+ <refname>{manname2}</refname>
+ <refname>{manname3}</refname>
+ <refname>{manname4}</refname>
+ <refname>{manname5}</refname>
+ <refname>{manname6}</refname>
+ <refname>{manname7}</refname>
+ <refname>{manname8}</refname>
+ <refname>{manname9}</refname>
+ <refname>{manname10}</refname>
+ <refname>{manname11}</refname>
+ <refname>{manname12}</refname>
+ <refname>{manname13}</refname>
+ <refname>{manname14}</refname>
+ <refname>{manname15}</refname>
+ <refname>{manname16}</refname>
+ <refname>{manname17}</refname>
+ <refname>{manname18}</refname>
+ <refname>{manname19}</refname>
+ <refname>{manname20}</refname>
+ <refname>{manname21}</refname>
+ <refname>{manname22}</refname>
+ <refname>{manname23}</refname>
+ <refname>{manname24}</refname>
+ <refname>{manname25}</refname>
+ <refname>{manname26}</refname>
+ <refname>{manname27}</refname>
+ <refname>{manname28}</refname>
+ <refname>{manname29}</refname>
+ <refname>{manname30}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
endif::backend-docbook[]
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 04/46] tools/lib/traceevent: libtraceevent Makefile "help" target
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (2 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 03/46] tools/lib/traceevent: Add support for man pages with multiple names Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 05/46] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Tzvetomir Stoyanov
` (42 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
This patch adds a new target to the traceevent Makefile - "help".
"make help" prints a description of all targets, supported by
the Makefile.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
tools/lib/traceevent/Makefile | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/tools/lib/traceevent/Makefile b/tools/lib/traceevent/Makefile
index 3764e003d1cc..0853861d0cd2 100644
--- a/tools/lib/traceevent/Makefile
+++ b/tools/lib/traceevent/Makefile
@@ -326,6 +326,21 @@ doc-install:
doc-uninstall:
$(call descend,Documentation,uninstall)
+help:
+ @echo 'Possible targets:'
+ @echo''
+ @echo ' all - default, compile the library and the'\
+ 'plugins'
+ @echo ' plugins - compile the plugins'
+ @echo ' install - install the library, the plugins,'\
+ 'the header and pkgconfig files'
+ @echo ' clean - clean the library and the plugins object files'
+ @echo ' doc - compile the documentation files - man'\
+ 'and html pages, in the Documentation directory'
+ @echo ' doc-clean - clean the documentation files'
+ @echo ' doc-install - install the man pages'
+ @echo ' doc-uninstall - uninstall the man pages'
+ @echo''
PHONY += force plugins
force:
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 05/46] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (3 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 04/46] tools/lib/traceevent: libtraceevent Makefile "help" target Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 06/46] tools/lib/traceevent: Man page for tep_get_header_page_size() Tzvetomir Stoyanov
` (41 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
This patch adds 4 new man pages for:
tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid,
tep_data_pid_from_comm,tep_cmdline_pid,tep_alloc,tep_free,tep_get_long_size,
tep_set_long_size,tep_set_flag, as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-commands.txt | 130 ++++++++++++++++++
.../Documentation/libtraceevent-handle.txt | 101 ++++++++++++++
.../Documentation/libtraceevent-long_size.txt | 78 +++++++++++
.../Documentation/libtraceevent-set_flag.txt | 90 ++++++++++++
4 files changed, 399 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-commands.txt b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt
new file mode 100644
index 000000000000..2db014d51d2c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt
@@ -0,0 +1,130 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid,tep_data_pid_from_comm,tep_cmdline_pid - handle pid to process name mappings
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
+int *tep_pid_is_registered*(struct tep_handle pass:[*]_tep_, int _pid_);
+const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_);
+struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_);
+int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_);
+--
+
+DESCRIPTION
+-----------
+These functions can be used to handle the mapping between pid and process name.
+The library builds a cache of these mappings, which is used to display the name of
+the process, instead of its pid. This information can be retrieved from
+tracefs/saved_cmdlines file.
+
+The _tep_register_comm()_ function registers a pid / process name mapping.
+The _pid_ argument is the process ID, the _comm_ argument is the process name,
+_tep_ is the event context. The _comm_ is copied internally.
+
+The _tep_pid_is_registered()_ function checks if a pid has a process name mapping
+registered. The _pid_ argument is the process ID, _tep_ is the event context.
+
+The _tep_data_comm_from_pid()_ function returns the process name for a given pid.
+The _pid_ argument is the process ID, _tep_ is the event context. The returned
+string should not be freed, but will be freed when the _tep_ handler is closed.
+
+The _tep_data_pid_from_comm()_ function returns a pid for a given process name.
+The _comm_ argument is the process name, _tep_ is the event context.
+The argument _next_ is the cmdline structure to search for the next pid.
+As there may be more than one pid for a given process, the result of this call
+can be passed back into a recurring call in the _next_ parameter, to search for
+the next pid. If _next_ is NULL, it will return the first pid associated with
+the _comm_. The function performs a linear search, so it may be slow.
+
+The _tep_cmdline_pid()_ function returns the pid associated with a given _cmdline_.
+The _tep_ argument is the event context.
+
+RETURN VALUE
+------------
+_tep_register_comm()_ function returns 0 on success, or -1 in case of an error.
+
+_tep_pid_is_registered()_ function returns 1 if the _pid_ has a process name
+mapped to it, 0 otherwise.
+
+_tep_data_comm_from_pid()_ function returns the process name as string, or the
+string "<...>" if there is no mapping for the given pid.
+
+_tep_data_pid_from_comm()_ function returns a pointer to a struct cmdline, that
+holds a pid for a given process, or NULL if none is found. This result can be
+passed back into a recurring call as the _next_ parameter of the function.
+
+_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_
+ is NULL, then -1 is returned.
+
+EXAMPLE
+-------
+The following example registers pid for command "ls", in context of event _tep_
+and performs various searches for pid / process name mappings:
+[source,c]
+--
+#include <event-parse.h>
+...
+int ls_pid = 1021;
+struct tep_handle *tep = tep_alloc();
+...
+ if (tep_register_comm(tep, "ls", ls_pid) != 0) {
+ /* Failed to register pid / command mapping */
+ }
+....
+ if (tep_pid_is_registered(tep, ls_pid) == 0) {
+ /* Command mapping for ls_pid is not registered */
+ }
+...
+ const char *comm = tep_data_comm_from_pid(tep, ls_pid);
+ if (comm) {
+ /* Found process name for ls_pid */
+ }
+...
+ int pid;
+ struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL);
+ while (cmd) {
+ pid = tep_cmdline_pid(tep, cmd);
+ /* Found pid for process "ls" */
+ cmd = tep_data_pid_from_comm(tep, "ls", cmd);
+ }
+--
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt
new file mode 100644
index 000000000000..7e1abe4dcda2
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt
@@ -0,0 +1,101 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_alloc,tep_free,tep_ref,tep_unref,tep_ref_get - Create, destroy, manage
+references of trace event parser context.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_handle pass:[*]*tep_alloc*(void);
+void *tep_free*(struct tep_handle pass:[*]_tep_);
+void *tep_ref*(struct tep_handle pass:[*]_tep_);
+void *tep_unref*(struct tep_handle pass:[*]_tep_);
+int *tep_ref_get*(struct tep_handle pass:[*]_tep_);
+--
+
+DESCRIPTION
+-----------
+These are the main functions to create and destroy tep_handle - the main
+structure, representing the trace event parser context. This context is used as
+the input parameter of most library APIs.
+
+The _tep_alloc()_ function allocates and initializes the tep context.
+
+The _tep_free()_ function will decrement the reference of the _tep_ handler.
+When there is no more references, then it will free the handler, as well
+as clean up all its resources that it had used. The argument _tep_ is
+the pointer to the trace event parser context.
+
+The _tep_ref()_ function adds a reference to the _tep_ handler.
+
+The _tep_unref()_ function removes a reference from the _tep_ handler. When
+the last reference is removed, the _tep_ is destroyed, and all resources that
+it had used are cleaned up.
+
+The _tep_ref_get()_ functions gets the current references of the _tep_ handler.
+
+RETURN VALUE
+------------
+_tep_alloc()_ returns a pointer to a newly created tep_handle structure.
+NULL is returned in case there is not enough free memory to allocate it.
+
+_tep_ref_get()_ returns the current references of _tep_.
+If _tep_ is NULL, 0 is returned.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+
+...
+struct tep_handle *tep = tep_alloc();
+...
+int ref = tep_ref_get(tep);
+tep_ref(tep);
+if ( (ref+1) != tep_ref_get(tep)) {
+ /* Something wrong happened, the counter is not incremented by 1 */
+}
+tep_unref(tep);
+...
+tep_free(tep);
+...
+--
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
new file mode 100644
index 000000000000..7cd69146d053
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_long_size,tep_set_long_size - Get / set the size of a long integer on
+the machine, where the trace is generated, in bytes
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_);
+void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_long_size()_ function returns the size of a long integer on the machine,
+where the trace is generated. The _tep_ argument is trace event parser context.
+
+The _tep_set_long_size()_ function sets the size of a long integer on the machine,
+where the trace is generated. The _tep_ argument is trace event parser context.
+The _long_size_ is the size of a long integer, in bytes.
+
+RETURN VALUE
+------------
+The _tep_get_long_size()_ function returns the size of a long integer on the machine,
+where the trace is generated, in bytes.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+tep_set_long_size(tep, 4);
+...
+int long_size = tep_get_long_size(tep);
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
new file mode 100644
index 000000000000..815b54156a57
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
@@ -0,0 +1,90 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_flag - Set a flag or combination of flags of trace event parser context
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_flag* {
+ _TEP_NSEC_OUTPUT_,
+ _TEP_DISABLE_SYS_PLUGINS_,
+ _TEP_DISABLE_PLUGINS_
+};
+void *tep_set_flag*(struct tep_handle pass:[*]_tep_, int _flag_);
+--
+
+DESCRIPTION
+-----------
+[verse]
+--
+The _tep_set_flag()_ function sets _flag_ or any combination of flags to _tep_ context.
+Flags are defined in *enum tep_flag*:
+ _TEP_NSEC_OUTPUT_ - print event's timestamp in nano seconds, instead of micro seconds.
+ _TEP_DISABLE_SYS_PLUGINS_ - disable plugins, located in system's plugin directory.
+ This directory is defined at library compile time, and usually
+ depends on library installation prefix: (install_preffix)/lib/traceevent/plugins
+ _TEP_DISABLE_PLUGINS_ - disable all library plugins:
+ - in system's plugin directory
+ - in directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_
+ - in user's home directory, _~/.traceevent/plugins_
+
+Note: plugin related flags must me set before calling _tep_load_plugins()_ API.
+--
+
+RETURN VALUE
+------------
+_tep_set_flag()_ functions has no return value.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+/* Set printing of timestamps in nano seconds and disable system plugins */
+tep_set_flag(tep, TEP_NSEC_OUTPUT | TEP_DISABLE_SYS_PLUGINS);
+...
+/* Disable all library plugins */
+tep_set_flag(tep, TEP_DISABLE_PLUGINS);
+...
+--
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 06/46] tools/lib/traceevent: Man page for tep_get_header_page_size()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (4 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 05/46] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 07/46] tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus() Tzvetomir Stoyanov
` (40 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create a man page for tep_get_header_page_size(),
as part of the libtraceevent API.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
| 73 +++++++++++++++++++
1 file changed, 73 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
--git a/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
new file mode 100644
index 000000000000..5810a4cdc2ea
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
@@ -0,0 +1,73 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_header_page_size - Get the size of a long integer, in kernel context.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_);
+
+--
+DESCRIPTION
+-----------
+The _tep_get_header_page_size()_ function returns the size of a long integer,
+in kernel context. The _tep_ argument is trace event parser context.
+This information is retrieved from /sys/kernel/debug/tracing/events/header_page,
+ "commit" field.
+
+RETURN VALUE
+------------
+The _tep_get_header_page_size()_ function returns the size of a long integer,
+in bytes
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ int lsize = tep_get_header_page_size(tep);
+ printf ("The size of a long in kernel context is %d bytes", lsize);
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 07/46] tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (5 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 06/46] tools/lib/traceevent: Man page for tep_get_header_page_size() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 08/46] tools/lib/traceevent: Man page for tep_is_file_bigendian() and tep_set_file_bigendian() Tzvetomir Stoyanov
` (39 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_get_cpus() and tep_set_cpus() as part of the
libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-cpus.txt | 77 +++++++++++++++++++
1 file changed, 77 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
new file mode 100644
index 000000000000..dab361517ad1
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
@@ -0,0 +1,77 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_cpus,tep_set_cpus - Get / set the number of CPUs, which have a tracing
+buffer representing it. Note, the buffer may be empty.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_cpus*(struct tep_handle pass:[*]_tep_);
+void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_cpus()_ function gets the number of CPUs, which have a tracing
+buffer representing it. The _tep_ argument is trace event parser context.
+
+The _tep_set_cpus()_ function sets the number of CPUs, which have a tracing
+buffer representing it. The _tep_ argument is trace event parser context.
+The _cpu_ argument is the number of CPUs with tracing data.
+
+RETURN VALUE
+------------
+The _tep_get_cpus()_ functions returns the number of CPUs, which have tracing
+data recorded.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ tep_set_cpus(tep, 5);
+...
+ printf("We have tracing data for %d CPUs", tep_get_cpus(tep));
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 08/46] tools/lib/traceevent: Man page for tep_is_file_bigendian() and tep_set_file_bigendian()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (6 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 07/46] tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 09/46] tools/lib/traceevent: Man page for tep_is_host_bigendian() and tep_set_host_bigendian() Tzvetomir Stoyanov
` (38 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_is_file_bigendian() and tep_set_file_bigendian()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-file_endian.txt | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
new file mode 100644
index 000000000000..2f37d151fa95
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
@@ -0,0 +1,89 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_file_bigendian,tep_set_file_bigendian - Get / set the endianness of the
+raw data being accessed by the tep handler.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+ TEP_LITTLE_ENDIAN = 0,
+ TEP_BIG_ENDIAN
+};
+
+int *tep_file_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+
+--
+DESCRIPTION
+-----------
+The _tep_file_bigendian()_ function returns the endianness of the raw data,
+being accessed by the tep handler. The _tep_ argument is trace event parser context.
+
+The _tep_set_file_bigendian()_ set the endianness of raw data being accessed
+by the tep handler. The _tep_ argument is trace event parser context.
+[verse]
+--
+The _endian_ argument is the endianness:
+ _TEP_LITTLE_ENDIAN_ - the raw data is in little endian format,
+ _TEP_BIG_ENDIAN_ - the raw data is in big endian format.
+--
+RETURN VALUE
+------------
+The _tep_file_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ tep_set_file_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+ if (TEP_BIG_ENDIAN == tep_file_bigendian(tep)) {
+ /* The raw data is in big endian */
+ } else {
+ /* The raw data is in little endian */
+ }
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 09/46] tools/lib/traceevent: Man page for tep_is_host_bigendian() and tep_set_host_bigendian()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (7 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 08/46] tools/lib/traceevent: Man page for tep_is_file_bigendian() and tep_set_file_bigendian() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 10/46] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format() Tzvetomir Stoyanov
` (37 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_is_host_bigendian() and tep_set_host_bigendian()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-host_endian.txt | 91 +++++++++++++++++++
1 file changed, 91 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
new file mode 100644
index 000000000000..de2aab90c8cf
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
@@ -0,0 +1,91 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_host_bigendian,tep_set_host_bigendian,tep_host_bigendian - Get / set the
+endianness of the machine running the current code.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+ TEP_LITTLE_ENDIAN = 0,
+ TEP_BIG_ENDIAN
+};
+
+int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+int tep_host_bigendian(void);
+--
+
+DESCRIPTION
+-----------
+The _tep_is_host_bigendian()_ function returns the endianness of the the machine
+running the current code. The _tep_ argument is the trace event parser context.
+
+The _tep_set_host_bigendian()_ set the endianness of the machine running the code.
+The _tep_ argument is trace event parser context. The _endian_ argument is the
+endianness:
+[verse]
+--
+ _TEP_LITTLE_ENDIAN_ - the machine is little endian,
+ _TEP_BIG_ENDIAN_ - the machine is big endian.
+--
+
+RETURN VALUE
+------------
+The _tep_is_host_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+ if (TEP_BIG_ENDIAN == tep_is_host_bigendian(tep)) {
+ /* The local host is big endian */
+ } else {
+ /* The local host is little endian */
+ }
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 10/46] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (8 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 09/46] tools/lib/traceevent: Man page for tep_is_host_bigendian() and tep_set_host_bigendian() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 16:28 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 11/46] tools/lib/traceevent: Man page for tep_get_page_size() and tep_set_page_size() Tzvetomir Stoyanov
` (36 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_is_latency_format() and tep_set_latency_format()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-latency_format.txt | 140 ++++++++++++++++++
1 file changed, 140 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
new file mode 100644
index 000000000000..ea82cbda7b7c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
@@ -0,0 +1,140 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_latency_format,tep_is_latency_format - Get / set "latency output" format.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
+int *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
+
+--
+
+DESCRIPTION
+-----------
+"Latency output" format prints information about interrupts being disabled,
+soft irq being disabled, the "need_resched" flag being set and preempt count.
+This information is recorded with every event, but by default is not printed.
+
+The _tep_set_latency_format()_ function enables the "latency output" printing.
+The _tep_ argument is trace event parser context. The _lat_ argument can be zero,
+for "latency output" disabled, or non zero for "latency output" enabled.
+Information is displayed with 6 characters. When a field is zero, or N/A, a pass:['.']
+is printed. Example:
+[verse]
+--
+ <idle>-0 0d.h1. 106467.859747: function: ktime_get <-- tick_check_idle
+--
+The 0d.h1. denotes this information. The first character is never a pass:['.']
+and represents what CPU the trace was recorded on (CPU 0). The pass:['d'] denotes
+that interrupts were disabled. The pass:['h'] means that this was called inside
+an interrupt handler. The pass:['1'] is the preemption disabled (preempt_count)
+was set to one. The two pass:['.']s are "need_resched" flag and kernel lock
+counter. If the "need_resched" flag is set, then that character would be a pass:['N'].
+See 'LATENCY FORMAT' section.
+
+The _tep_is_latency_format()_ function returns if "latency output" is enabled.
+
+This "Latency output" setting affects output of _tep_print_event_task()_
+and _tep_print_event_time()_ APIs.
+
+LATENCY FORMAT
+--------------
+The latency format displays 5 or more fields:
+[verse]
+--
+ CPU #, interrupt state, scheduling state, current context, and preemption count.
+
+ Field 1 is the CPU number (starting with zero).
+
+ Field 2 is the interrupt enabled state:
+ d : Interrupts are disabled
+ . : Interrupts are enabled
+ X : The architecture does not support this information
+
+ Field 3 is the "need resched" state.
+ N : The task is set to call the scheduler when possible, as another
+ higher priority task may need to be scheduled in.
+ . : The task is not set to call the scheduler.
+
+ Field 4 is the context state.
+ . : Normal context
+ s : Soft interrupt context
+ h : Hard interrupt context
+ H : Hard interrupt context which triggered during soft interrupt context.
+ z : NMI context
+ Z : NMI context which triggered during hard interrupt context
+
+ Field 5 is the preemption count.
+ . : The preempt count is zero.
+
+ On preemptible kernels (where the task can be scheduled out in
+ arbitrary locations while in kernel context), The preempt count,
+ when non zero, will prevent the kernel from scheduling out the
+ current task. The preempt count number is displayed when it is not
+ zero.
+--
+Depending on the kernel, it may show other fields (lock depth,
+or migration disabled, which are unique to specialized kernels).
+
+RETURN VALUE
+------------
+
+The _tep_is_latency_format()_ function returns non zero if "latency output"
+is enabled, or zero if it is disabled.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ tep_set_latency_format(tep, 1);
+...
+ if (tep_is_latency_format(tep)) {
+ /* latency output format is enabled */
+ } else {
+ /* latency output format is disabled */
+ }
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-ltraceevent*
+ Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_, tep_print_event_task(3), tep_print_event_time(3)
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 10/46] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format()
2019-03-08 13:36 ` [PATCH v4 10/46] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format() Tzvetomir Stoyanov
@ 2019-03-13 16:28 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 16:28 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:18 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> + <idle>-0 0d.h1. 106467.859747: function: ktime_get <-- tick_check_idle
> +--
> +The 0d.h1. denotes this information. The first character is never a pass:['.']
> +and represents what CPU the trace was recorded on (CPU 0). The pass:['d'] denotes
> +that interrupts were disabled. The pass:['h'] means that this was called inside
> +an interrupt handler. The pass:['1'] is the preemption disabled (preempt_count)
> +was set to one. The two pass:['.']s are "need_resched" flag and kernel lock
There is no kernel lock counter.
Should delete that last '.' in the example.
-- Steve
> +counter. If the "need_resched" flag is set, then that character would be a pass:['N'].
> +See 'LATENCY FORMAT' section.
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 11/46] tools/lib/traceevent: Man page for tep_get_page_size() and tep_set_page_size()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (9 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 10/46] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 12/46] tools/lib/traceevent: Man page for tep_strerror() Tzvetomir Stoyanov
` (35 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_get_page_size() and tep_set_page_size()
as part of the libtraceevent APIs. It also alignes description of
the functions (in the C code) with the man pages.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-page_size.txt | 80 +++++++++++++++++++
1 file changed, 80 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
new file mode 100644
index 000000000000..0701001fffcf
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
@@ -0,0 +1,80 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_page_size,tep_set_page_size - Get / set the size of a memory page on the
+machine, where the trace is generated
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
+void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_page_size()_ function returns the size of a memory page on
+the machine, where the trace is generated. The _tep_ argument is trace
+event parser context.
+
+The _tep_set_page_size()_ function stores in the _tep_ context the size of a
+memory page on the machine, where the trace is generated.
+The _tep_ argument is trace event parser context.
+The _page_size_ argument is the size of a memory page, in bytes.
+
+RETURN VALUE
+------------
+The _tep_get_page_size()_ function returns size of the memory page, in bytes.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ int page_size = 4096;
+ tep_set_page_size(tep, page_size);
+ if ( 4096 != tep_get_page_size(tep)) {
+ /* Something wrong happened, page size is not set as expected */
+ }
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 12/46] tools/lib/traceevent: Man page for tep_strerror()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (10 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 11/46] tools/lib/traceevent: Man page for tep_get_page_size() and tep_set_page_size() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 13/46] tools/lib/traceevent: Man page for tep_register_trace_clock() Tzvetomir Stoyanov
` (34 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_strerror() as part of libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-strerror.txt | 78 +++++++++++++++++++
1 file changed, 78 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
new file mode 100644
index 000000000000..b0785a813b57
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_strerror - Returns a string describing regular errno and tep error number.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_);
+
+--
+DESCRIPTION
+-----------
+The _tep_strerror()_ function converts tep error number into a human readable string.
+The _tep_ argument is trace event parser context. The _errnum_ is a regular errno,
+defined in errno.h, or a tep error number. The string, describing this error number
+is copied in the _buf_ argument. The _buflen_ argument is the size of the _buf_.
+
+RETURN VALUE
+------------
+The _tep_strerror()_ function returns 0, if a valid _errnum_ is passed and the
+string is copied into _buf_. If _errnum_ is not a valid error number, -1 is returned
+and _buf_ is not modified.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+char buf[32];
+char *pool = calloc(1, 128);
+if (tep == NULL) {
+ tep_strerror(tep, TEP_ERRNO__MEM_ALLOC_FAILED, buf, 32);
+ printf ("The pool is not initialized, %s", buf);
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 13/46] tools/lib/traceevent: Man page for tep_register_trace_clock()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (11 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 12/46] tools/lib/traceevent: Man page for tep_strerror() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 14/46] tools/lib/traceevent: Man pages for tep_register_event_handler() and tep_unregister_event_handler() Tzvetomir Stoyanov
` (33 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_register_trace_clock()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-reg_clock.txt | 77 +++++++++++++++++++
1 file changed, 77 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
new file mode 100644
index 000000000000..8bf6c5348fcf
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
@@ -0,0 +1,77 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_register_trace_clock - Registers the clock, used for the timestamp of
+the events.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_);
+--
+
+DESCRIPTION
+-----------
+The _tep_register_trace_clock()_ function registers the clock, used for
+the timestamps of the events. When an event is recorded, a timestamp is attached
+to it. This timestamp comes from a specified clock. Supported clocks can be seen
+in tracefs/trace_clock, the selected one is in square brackets.
+The _tep_ argument is the trace event parser context. The _trace_clock_ argument
+is the name of the clock, the string is copied internally.
+
+RETURN VALUE
+------------
+The _tep_register_trace_clock()_ function returns 0 in case of success.
+If there is not enough memory to copy the _trace_clock_ string -1 is returned
+and errno is set to ENOMEM.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ if(tep_register_trace_clock(tep, "local") != 0) {
+ /* Failed to register the clock */
+ }
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 14/46] tools/lib/traceevent: Man pages for tep_register_event_handler() and tep_unregister_event_handler()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (12 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 13/46] tools/lib/traceevent: Man page for tep_register_trace_clock() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string() Tzvetomir Stoyanov
` (32 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_register_event_handler() and tep_unregister_event_handler()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-reg_event_handler.txt | 129 ++++++++++++++++++
1 file changed, 129 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
new file mode 100644
index 000000000000..bf96dc825e19
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
@@ -0,0 +1,129 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_register_event_handler,tep_unregister_event_handler - Register / unregisters
+a callback function to parse an event information.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_reg_handler* {
+ _TEP_REGISTER_SUCCESS_,
+ _TEP_REGISTER_SUCCESS_OVERWRITE_,
+};
+
+int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_);
+int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_);
+
+typedef int (*pass:[*]tep_event_handler_func*)(struct trace_seq pass:[*]s, struct tep_record pass:[*]record, struct tep_event pass:[*]event, void pass:[*]context);
+--
+
+DESCRIPTION
+-----------
+The _tep_register_event_handler()_ function registers a handler function,
+which is going to be called to parse the information for a given event.
+The _tep_ argument is the trace event parser context. The _id_ argument is
+the id of the event. The _sys_name_ argument is the name of the system,
+the event belongs to. The _event_name_ argument is the name of the event.
+If _id_ is >= 0, it is used to find the event, otherwise _sys_name_ and
+_event_name_ are used. The _func_ is a pointer to the function, which is going
+to be called to parse the event information. The _context_ argument is a pointer
+to the context data, which will be passed to the _func_. If a handler function
+for the same event is already registered, it will be overridden with the new
+one. This mechanism allows a developer to override the parsing of a given event.
+If for some reason the default print format is not sufficient, the developer
+can register a function for an event to be used to parse the data instead.
+
+The _tep_unregister_event_handler()_ function unregisters the handler function,
+previously registered with _tep_register_event_handler()_. The _tep_ argument
+is the trace event parser context. The _id_, _sys_name_, _event_name_, _func_,
+and _context_ are the same arguments, as when the callback function _func_ was
+registered.
+
+The _tep_event_handler_func_ is the type of the custom event handler
+function. The _s_ argument is the trace sequence, it can be used to create a
+custom string, describing the event. A _record_ to get the event from is passed
+as input parameter and also the _event_ - the handle to the record's event. The
+_context_ is custom context, set when the custom event handler is registered.
+
+RETURN VALUE
+------------
+The _tep_register_event_handler()_ function returns _TEP_REGISTER_SUCCESS_
+if the new handler is registered successfully or _TEP_REGISTER_SUCCESS_OVERWRITE_ if
+an existing handler is overwritten. If there is not enough memory to complete
+the registration, TEP_ERRNO__MEM_ALLOC_FAILED is returned.
+
+The _tep_unregister_event_handler()_ function returns 0 if _func_ was removed
+successful or, -1 if the event was not found.
+
+The _tep_event_handler_func_ should return -1 in case of an error, or 0 otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+int custom_event_handler(struct trace_seq *s, struct tep_record *record,
+ struct tep_event *event, void *context)
+{
+ trace_seq_printf(s, "kvm_exit event");
+ return 0;
+}
+...
+ if (tep_register_event_handler(tep, -1, "kvm", "kvm_exit",
+ custom_event_handler, NULL)) {
+ /* Failed to register the handler for event "kvm_exit" from "kvm" system */
+ }
+...
+ if (tep_unregister_event_handler(pevent, -1, "kvm", "kvm_exit",
+ custom_event_handler, NULL) != ) {
+ /* Failed to unregister the handler for event "kvm_exit" from "kvm" system */
+ }
+
+--
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (13 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 14/46] tools/lib/traceevent: Man pages for tep_register_event_handler() and tep_unregister_event_handler() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 16:57 ` Steven Rostedt
2019-03-13 16:59 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 16/46] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function() Tzvetomir Stoyanov
` (31 subsequent siblings)
46 siblings, 2 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_register_function() and tep_register_print_string()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-reg_funcstr.txt | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
new file mode 100644
index 000000000000..fdb9e0352586
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
@@ -0,0 +1,89 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_register_function, tep_register_print_string - Registers a function / string
+with a given address.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
+int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
+--
+
+DESCRIPTION
+-----------
+The _tep_register_function()_ function registers a function name with an
+address and module. The _tep_ argument is the trace event parser context. The
+_name_ is the name of the function, the string is copied internally. The _addr_
+is the start address of the function. The _mod_ is the kernel module
+the function may be in (NULL for none).
+
+The _tep_register_print_string()_ function registers a string by the address
+it was stored in the kernel. The _tep_ argument is the trace event parser
+context. The _fmt_ is the string to register, it is copied internally. The _addr_
+is the address the string was located at.
+
+RETURN VALUE
+------------
+The _tep_register_function()_ function returns 0 in case of success. In case of
+an error -1 is returned, and errno is set to the appropriate error number.
+
+The _tep_register_print_string()_ function returns 0 in case of success. In case
+of an error -1 is returned, and errno is set to the appropriate error number.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+ if (tep_register_function(tep, "my_custom_func",
+ (unsigned long long) 0x12345678, NULL) != 0) {
+ /* Failed to register my_custom_func address mapping */
+ }
+...
+ if (tep_register_print_string(tep, "print string",
+ (unsigned long long) 0x87654321, NULL) != 0) {
+ /* Failed to register "print string" address mapping */
+ }
+--
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string()
2019-03-08 13:36 ` [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string() Tzvetomir Stoyanov
@ 2019-03-13 16:57 ` Steven Rostedt
2019-03-13 16:59 ` Steven Rostedt
1 sibling, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 16:57 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:23 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_register_function() and tep_register_print_string()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-reg_funcstr.txt | 89 +++++++++++++++++++
> 1 file changed, 89 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
> new file mode 100644
> index 000000000000..fdb9e0352586
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
> @@ -0,0 +1,89 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_register_function, tep_register_print_string - Registers a function / string
> +with a given address.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
> +int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_register_function()_ function registers a function name with an
> +address and module. The _tep_ argument is the trace event parser context. The
> +_name_ is the name of the function, the string is copied internally. The _addr_
> +is the start address of the function. The _mod_ is the kernel module
> +the function may be in (NULL for none).
I would elaborate here more about what this means. What is registered
is kernel function name that is mapped to an address that will be used
in function look ups. For the function tracer or events that have a
"%pF" or "%pS" in the format string. It is common to pass in the
kallsyms function names with their corresponding addresses with this
function.
> +
> +The _tep_register_print_string()_ function registers a string by the address
> +it was stored in the kernel. The _tep_ argument is the trace event parser
> +context. The _fmt_ is the string to register, it is copied internally. The _addr_
> +is the address the string was located at.
Some strings internal to the kernel with static address are passed to
certain events. The "%s" in the format field which has an address will
need to know what string would be at that address. The
tep_register_print_string() supplies the parsing with the mapping
between kernel addresses and those strings.
-- Steve
> +
> +RETURN VALUE
> +------------
> +The _tep_register_function()_ function returns 0 in case of success. In case of
> +an error -1 is returned, and errno is set to the appropriate error number.
> +
> +The _tep_register_print_string()_ function returns 0 in case of success. In case
> +of an error -1 is returned, and errno is set to the appropriate error number.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> + if (tep_register_function(tep, "my_custom_func",
> + (unsigned long long) 0x12345678, NULL) != 0) {
> + /* Failed to register my_custom_func address mapping */
> + }
> +...
> + if (tep_register_print_string(tep, "print string",
> + (unsigned long long) 0x87654321, NULL) != 0) {
> + /* Failed to register "print string" address mapping */
> + }
> +--
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> + Header file to include in order to have access to the library APIs.
> +*-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
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string()
2019-03-08 13:36 ` [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string() Tzvetomir Stoyanov
2019-03-13 16:57 ` Steven Rostedt
@ 2019-03-13 16:59 ` Steven Rostedt
1 sibling, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 16:59 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:23 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> + if (tep_register_function(tep, "my_custom_func",
> + (unsigned long long) 0x12345678, NULL) != 0) {
There's a whitespace bug in the above string.
Also, I wouldn't use "my_custom_func" as the example name, as its not
for custom names. I would use "kernel_function_X" or something similar.
-- Steve
> + /* Failed to register my_custom_func address mapping */
> + }
> +...
> + if (tep_register_print_string(tep, "print string",
> + (unsigned long long) 0x87654321, NULL) != 0) {
> + /* Failed to register "print string" address mapping */
> + }
> +--
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 16/46] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (14 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 15/46] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:23 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 17/46] tools/lib/traceevent: Man page for tep_read_number() Tzvetomir Stoyanov
` (30 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_register_print_function() and tep_unregister_print_function()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-reg_print_func.txt | 128 ++++++++++++++++++
1 file changed, 128 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
new file mode 100644
index 000000000000..59cef18b71f1
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
@@ -0,0 +1,128 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_register_print_function,tep_unregister_print_function - Registers / Unregisters
+a helper function.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_func_arg_type* {
+ TEP_FUNC_ARG_VOID,
+ TEP_FUNC_ARG_INT,
+ TEP_FUNC_ARG_LONG,
+ TEP_FUNC_ARG_STRING,
+ TEP_FUNC_ARG_PTR,
+ TEP_FUNC_ARG_MAX_TYPES
+};
+
+typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args);
+
+int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
+int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
+--
+
+DESCRIPTION
+-----------
+Some events may have helper functions in the print format arguments. This allows
+a plugin to dynamically create a way to process one of these functions.
+
+The _tep_register_print_function()_ registers such helper function. The _tep_
+argument is the trace event parser context. The _func_ argument is the address
+of the helper function. The _ret_type_ argument is the return type of the
+helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name
+of the helper function, as seen in the print format arguments. The _..._ is a
+variable list of _tep_func_arg_type_ enums, the _func_ function arguments.
+This list must end with _TEP_FUNC_ARG_VOID_.
+
+The _tep_unregister_print_function()_ unregisters a helper function, previously
+registered with _tep_register_print_function()_. The _tep_ argument is the
+trace event parser context. The _func_ and _name_ arguments are the same, used
+when the helper function was registered.
+
+The _tep_func_handler_ is the type of the helper function. The _s_ argument is
+the trace sequence, it can be used to create a custom string.
+The _args_ is a list of arguments, defined when the helper function was
+registered.
+
+RETURN VALUE
+------------
+The _tep_register_print_function()_ function returns 0 in case of success.
+In case of an error, TEP_ERRNO_... code is returned.
+
+The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in
+case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+static long long
+process_custom_helper(struct trace_seq *s, unsigned long long *args)
+{
+ unsigned long long param = args[0];
+ trace_seq_printf(s, "the helper was called, with argument %lld", param);
+ return 0;
+}
+...
+ if ( tep_register_print_function(tep,
+ process_custom_helper,
+ TEP_FUNC_ARG_STRING,
+ "custom_helper",
+ TEP_FUNC_ARG_LONG,
+ TEP_FUNC_ARG_VOID) != 0) {
+ /* Failed to register my process_custom_helper function */
+ }
+...
+ if (tep_unregister_print_function(tep, process_custom_helper,
+ "custom_helper") != 0) {
+ /* Failed to unregister my process_custom_helper function */
+ }
+--
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 16/46] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function()
2019-03-08 13:36 ` [PATCH v4 16/46] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function() Tzvetomir Stoyanov
@ 2019-03-13 17:23 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:23 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:24 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_register_print_function() and tep_unregister_print_function()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-reg_print_func.txt | 128 ++++++++++++++++++
> 1 file changed, 128 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> new file mode 100644
> index 000000000000..59cef18b71f1
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> @@ -0,0 +1,128 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_register_print_function,tep_unregister_print_function - Registers / Unregisters
> +a helper function.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +enum *tep_func_arg_type* {
> + TEP_FUNC_ARG_VOID,
> + TEP_FUNC_ARG_INT,
> + TEP_FUNC_ARG_LONG,
> + TEP_FUNC_ARG_STRING,
> + TEP_FUNC_ARG_PTR,
> + TEP_FUNC_ARG_MAX_TYPES
> +};
> +
> +typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args);
> +
> +int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
> +int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
> +--
> +
> +DESCRIPTION
> +-----------
> +Some events may have helper functions in the print format arguments. This allows
> +a plugin to dynamically create a way to process one of these functions.
> +
> +The _tep_register_print_function()_ registers such helper function. The _tep_
> +argument is the trace event parser context. The _func_ argument is the address
> +of the helper function. The _ret_type_ argument is the return type of the
I would say "The _func_ argument is a pointer to the helper function".
> +helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name
> +of the helper function, as seen in the print format arguments. The _..._ is a
> +variable list of _tep_func_arg_type_ enums, the _func_ function arguments.
> +This list must end with _TEP_FUNC_ARG_VOID_.
We should elaborate more what this is for. Some events have internal
functions called that appear in the print format output. For example,
tracefs/events/i915/g4x_wm/format has:
print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s", ((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary, REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane, REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane, REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc)
Where inside the kernel they define a function:
static const char *yesno(int x)
{
static const char *yes = "yes";
static const char *no = "no";
return x ? yes : no;
}
Now the event parser has no idea how to handle this "yesno()" function.
But if we have:
static const char *yesno(int x)
{
return x ? "yes" : "no";
}
tep_register_print_function(tep, yesno, TEP_FUNC_ARG_STRING, "yesno",
TEP_FUNC_ARG_INT, TEP_FUNC_ARG_VOID);
Then when the parser encounters this "yesno()" function, it will know
how to handle it.
This actually is a good example to use in the man page!
-- Steve
> +
> +The _tep_unregister_print_function()_ unregisters a helper function, previously
> +registered with _tep_register_print_function()_. The _tep_ argument is the
> +trace event parser context. The _func_ and _name_ arguments are the same, used
> +when the helper function was registered.
> +
> +The _tep_func_handler_ is the type of the helper function. The _s_ argument is
> +the trace sequence, it can be used to create a custom string.
> +The _args_ is a list of arguments, defined when the helper function was
> +registered.
> +
> +RETURN VALUE
> +------------
> +The _tep_register_print_function()_ function returns 0 in case of success.
> +In case of an error, TEP_ERRNO_... code is returned.
> +
> +The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in
> +case of an error.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +#include <trace-seq.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +static long long
> +process_custom_helper(struct trace_seq *s, unsigned long long *args)
> +{
> + unsigned long long param = args[0];
> + trace_seq_printf(s, "the helper was called, with argument %lld", param);
> + return 0;
> +}
> +...
> + if ( tep_register_print_function(tep,
> + process_custom_helper,
> + TEP_FUNC_ARG_STRING,
> + "custom_helper",
> + TEP_FUNC_ARG_LONG,
> + TEP_FUNC_ARG_VOID) != 0) {
> + /* Failed to register my process_custom_helper function */
> + }
> +...
> + if (tep_unregister_print_function(tep, process_custom_helper,
> + "custom_helper") != 0) {
> + /* Failed to unregister my process_custom_helper function */
> + }
> +--
> +
> +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
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 17/46] tools/lib/traceevent: Man page for tep_read_number()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (15 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 16/46] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:26 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 18/46] tools/lib/traceevent: Man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record() Tzvetomir Stoyanov
` (29 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_read_number() as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-endian_read.txt | 76 +++++++++++++++++++
1 file changed, 76 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
new file mode 100644
index 000000000000..803819dbf51b
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
@@ -0,0 +1,76 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_read_number - Reads a number from raw data.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_read_number()_ function reads an integer from raw data, taking into
+account the endianness of the raw data and the current host. The _tep_ argument
+is the trace event parser context. The _ptr_ is a pointer to the raw data, where
+the integer is, and the _size_ is the size of the integer.
+
+RETURN VALUE
+------------
+The _tep_read_number()_ function returns the integer in the byte order of
+the current host. In case of an error, 0 is returned.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+void process_record(struct tep_record *record)
+{
+ int data = tep_read_number(tep, record->data, 4);
+ /* Read the first 4 bytes of the record as integer */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 17/46] tools/lib/traceevent: Man page for tep_read_number()
2019-03-08 13:36 ` [PATCH v4 17/46] tools/lib/traceevent: Man page for tep_read_number() Tzvetomir Stoyanov
@ 2019-03-13 17:26 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:26 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:25 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> +struct tep_handle *tep = tep_alloc();
> +...
> +void process_record(struct tep_record *record)
> +{
> + int data = tep_read_number(tep, record->data, 4);
> + /* Read the first 4 bytes of the record as integer */
I would use a better example like:
int offset = 24;
int data = tep_read_number(tep, record->data + offset, 4);
/* Read the 4 bytes at the offset 24 of data as an integer */
-- Steve
> +}
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 18/46] tools/lib/traceevent: Man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (16 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 17/46] tools/lib/traceevent: Man page for tep_read_number() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events() Tzvetomir Stoyanov
` (28 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_find_event(), tep_find_event_by_name()
and tep_find_event_by_record() as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-event_find.txt | 99 +++++++++++++++++++
1 file changed, 99 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
new file mode 100644
index 000000000000..961309f24491
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
@@ -0,0 +1,99 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_find_event,tep_find_event_by_name,tep_find_event_by_record - Find events by given key.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_);
+struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_);
+struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_);
+--
+
+DESCRIPTION
+-----------
+This set of functions can be used to search for an event, based on a given
+criteria. All functions require a pointer to a _tep_, trace event parser context.
+
+The _tep_find_event()_ function searches for an event by given event _id_.
+
+The tep_find_event_by_name()_ function searches for an event by given
+event _name_, under the system _sys_. If the _sys_ is NULL (not specified),
+the first event with _name_ is returned.
+
+The tep_find_event_by_record()_ function searches for an event from a given
+_record_.
+
+RETURN VALUE
+------------
+All these functions return a pointer to the found event, or NULL if there is no
+such event.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event *event;
+
+event = tep_find_event(tep, 1857);
+if (event == NULL) {
+ /* There is no event with ID 1857 */
+}
+
+event = tep_find_event_by_name(tep, "kvm", "kvm_exit");
+if (event == NULL) {
+ /* There is no kvm_exit event, from kvm system */
+}
+
+void event_from_record(struct tep_record *record)
+{
+ struct tep_event *event = tep_find_event_by_record(tep, record);
+ if (event == NULL) {
+ /* There is no event from given record */
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (17 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 18/46] tools/lib/traceevent: Man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:29 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 20/46] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time() Tzvetomir Stoyanov
` (27 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_list_events() as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-event_list.txt | 94 +++++++++++++++++++
1 file changed, 94 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
new file mode 100644
index 000000000000..97b2e0922900
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
@@ -0,0 +1,94 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_list_events - Get list of events, sorted by given criteria.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_event_sort_type* {
+ _TEP_EVENT_SORT_ID_,
+ _TEP_EVENT_SORT_NAME_,
+ _TEP_EVENT_SORT_SYSTEM_,
+};
+
+struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
+--
+
+DESCRIPTION
+-----------
+The _tep_list_events()_ function returns an array of pointers to the events,
+sorted by the _sort_type_ criteria. The last element of the array is NULL.
+The returned memory must not be freed, it is managed by the library.
+The _tep_ argument is trace event parser context. The _sort_type_ argument is
+the required sort criteria:
+[verse]
+--
+ _TEP_EVENT_SORT_ID_ - sort by the event ID.
+ _TEP_EVENT_SORT_NAME_ - sort by the event (name, system, id) triplet.
+ _TEP_EVENT_SORT_SYSTEM_ - sort by the event (system, name, id) triplet.
+--
+
+RETURN VALUE
+------------
+The _tep_list_events()_ function returns an array of pointers to events.
+In case of an error, NULL is returned.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+int i=0;
+struct tep_event_format **events = tep_list_events(tep, TEP_EVENT_SORT_ID);
+if (events == NULL) {
+ /* Failed to get the events, sorted by ID */
+} else {
+ while(events[i]) {
+ /* walk through the list of the events, sorted by the ID */
+ i++;
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events()
2019-03-08 13:36 ` [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events() Tzvetomir Stoyanov
@ 2019-03-13 17:29 ` Steven Rostedt
2019-03-14 13:05 ` Tzvetomir Stoyanov
0 siblings, 1 reply; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:29 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:27 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man page for tep_list_events() as part of the libtraceevent APIs.
>
We should probably include tep_list_events_copy() in this man page.
Where one is not to be freed, and the other is.
-- Steve
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-event_list.txt | 94 +++++++++++++++++++
> 1 file changed, 94 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
>
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events()
2019-03-13 17:29 ` Steven Rostedt
@ 2019-03-14 13:05 ` Tzvetomir Stoyanov
2019-03-14 13:39 ` Steven Rostedt
0 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-14 13:05 UTC (permalink / raw)
To: Steven Rostedt; +Cc: linux-trace-devel
On Wed, Mar 13, 2019 at 7:29 PM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Fri, 8 Mar 2019 15:36:27 +0200
> Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> > Create man page for tep_list_events() as part of the libtraceevent APIs.
> >
>
> We should probably include tep_list_events_copy() in this man page.
> Where one is not to be freed, and the other is.
I'll update the man page once we introduce tep_list_events_copy() to
tools/lib/traceevent, currently this new API is part of trace-cmd only.
>
> -- Steve
>
> > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> > ---
> > .../libtraceevent-event_list.txt | 94 +++++++++++++++++++
> > 1 file changed, 94 insertions(+)
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
> >
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events()
2019-03-14 13:05 ` Tzvetomir Stoyanov
@ 2019-03-14 13:39 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-14 13:39 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Thu, 14 Mar 2019 13:05:15 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> > We should probably include tep_list_events_copy() in this man page.
> > Where one is not to be freed, and the other is.
>
> I'll update the man page once we introduce tep_list_events_copy() to
> tools/lib/traceevent, currently this new API is part of trace-cmd only.
Ah, I guess I should go and sort out all the patches that need to go
upstream too ;-)
I'll start by diffing the two trees and then searching for the patches
that make the updates.
-- Steve
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 20/46] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (18 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 19/46] tools/lib/traceevent: Man page for tep_list_events() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:33 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 21/46] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count() Tzvetomir Stoyanov
` (26 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_print_event(), tep_print_event_data(),
tep_event_info(), tep_print_event_task() and tep_print_event_time()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-event_print.txt | 126 ++++++++++++++++++
1 file changed, 126 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..8fea72705645
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
@@ -0,0 +1,126 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_print_event,tep_print_event_data,tep_event_info,tep_print_event_task,tep_print_event_time - 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_);
+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_);
+--
+
+DESCRIPTION
+-----------
+The _tep_print_event_time()_ function prints the timestamp of the _record_ using
+the given _event_ information as trace sequence in _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 prints the task command, pid and CPU of
+the _record_ using the given _event_ information as trace sequence in _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 as trace sequence in
+_s_.
+
+The _tep_print_event_data()_ function writes the _event_ name as trace
+sequence in _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 prints the _record_ information as trace
+sequence in _s_. It finds the corresponding event and calls
+_tep_print_event_task()_,_tep_print_event_time()_ and _tep_print_event_data()_
+to parse and print the information.
+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.
+
+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);
+ }
+}
+...
+--
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 20/46] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time()
2019-03-08 13:36 ` [PATCH v4 20/46] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time() Tzvetomir Stoyanov
@ 2019-03-13 17:33 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:33 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:28 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_print_event(), tep_print_event_data(),
> tep_event_info(), tep_print_event_task() and tep_print_event_time()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-event_print.txt | 126 ++++++++++++++++++
> 1 file changed, 126 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..8fea72705645
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
> @@ -0,0 +1,126 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_print_event,tep_print_event_data,tep_event_info,tep_print_event_task,tep_print_event_time - 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_);
> +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_);
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_print_event_time()_ function prints the timestamp of the _record_ using
> +the given _event_ information as trace sequence in _s_.
The above should be worded different, as it sounds like it gets the
information from _s_.
Should say "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 prints the task command, pid and CPU of
> +the _record_ using the given _event_ information as trace sequence in _s_.
Same here.
> +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 as trace sequence in
> +_s_.
The above is correct and what the other two should look like.
> +
> +The _tep_print_event_data()_ function writes the _event_ name as trace
> +sequence in _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 above needs to be fixed.
> +
> +The _tep_print_event()_ function prints the _record_ information as trace
> +sequence in _s_. It finds the corresponding event and calls
The above needs to be fixed.
-- Steve
> +_tep_print_event_task()_,_tep_print_event_time()_ and _tep_print_event_data()_
> +to parse and print the information.
> +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.
> +
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 21/46] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (19 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 20/46] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:35 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 22/46] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field() Tzvetomir Stoyanov
` (25 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_get_first_event() and tep_get_events_count()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-events.txt | 87 +++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-events.txt b/tools/lib/traceevent/Documentation/libtraceevent-events.txt
new file mode 100644
index 000000000000..b8f81bb9ece9
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-events.txt
@@ -0,0 +1,87 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_first_event,tep_get_events_count - Access events.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_);
+int *tep_get_events_count*(struct tep_handle pass:[*]_tep_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_first_event()_ function returns a pointer to the first event.
+As events are stored in an array, this function returns the pointer to the
+beginning of the array. The _tep_ argument is trace event parser context.
+
+The _tep_get_events_count()_ function returns the number of the events
+in the array. The _tep_ argument is trace event parser context.
+
+RETURN VALUE
+------------
+The _tep_get_first_event()_ returns a pointer to the first event. NULL is
+returned in case of error, or in case there are no events.
+
+The _tep_get_events_count()_ returns the number of the events. 0 is
+returned in case of error, or in case there are no events.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+int i,count = tep_get_events_count(tep);
+struct tep_event *event, *events = tep_get_first_event(tep);
+
+if (events == NULL) {
+ /* There are no events */
+} else {
+ for (i=0; i<count; i++) {
+ event = (events+i);
+ /* process events[i] */
+ }
+}
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 21/46] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count()
2019-03-08 13:36 ` [PATCH v4 21/46] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count() Tzvetomir Stoyanov
@ 2019-03-13 17:35 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:35 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:29 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +int i,count = tep_get_events_count(tep);
> +struct tep_event *event, *events = tep_get_first_event(tep);
> +
> +if (events == NULL) {
> + /* There are no events */
> +} else {
> + for (i=0; i<count; i++) {
The examples should follow Linux coding style ;-)
That is, tabs and not spaces, and space out the for:
for (i = 0; i < count; i++) {
-- Steve
> + event = (events+i);
> + /* process events[i] */
> + }
> +}
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 22/46] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (20 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 21/46] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 17:42 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 23/46] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw() Tzvetomir Stoyanov
` (24 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_find_common_field(), tep_find_field()
and tep_find_any_field() as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-field_find.txt | 98 +++++++++++++++++++
1 file changed, 98 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
new file mode 100644
index 000000000000..b941988429a0
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
@@ -0,0 +1,98 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_find_common_field,tep_find_field,tep_find_any_field - Search for a field in an event.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
+struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
+--
+
+DESCRIPTION
+-----------
+These functions search for a field with given name in an event.
+
+The _tep_find_common_field()_ function searches for a common field with _name_
+in the _event_.
+
+The _tep_find_field()_ function searches for an event specific field with
+_name_ in the _event_.
+
+The _tep_find_any_field()_ function searches for any field with _name_ in the
+_event_.
+
+RETURN VALUE
+------------
+The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_
+functions return a pointer to the found field, or NULL in case there is no field
+with the requested name.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
+...
+ struct tep_format_field *field;
+
+ field = tep_find_common_field(event, "common_pid");
+ if (field == NULL) {
+ /* Cannot find "common_pid" common field in the event */
+ }
+
+ field = tep_find_field(event, "softexpires");
+ if (field == NULL) {
+ /* Cannot find "softexpires" event specific field in the event */
+ }
+
+ field = tep_find_any_field(event, "mode");
+ if (field == NULL) {
+ /* Cannot find "mode" field in the event */
+ }
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 22/46] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field()
2019-03-08 13:36 ` [PATCH v4 22/46] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field() Tzvetomir Stoyanov
@ 2019-03-13 17:42 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 17:42 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:30 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_find_common_field(), tep_find_field()
> and tep_find_any_field() as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-field_find.txt | 98 +++++++++++++++++++
> 1 file changed, 98 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
> new file mode 100644
> index 000000000000..b941988429a0
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
> @@ -0,0 +1,98 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_find_common_field,tep_find_field,tep_find_any_field - Search for a field in an event.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
> +struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
> +struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
> +--
> +
> +DESCRIPTION
> +-----------
> +These functions search for a field with given name in an event.
> +
> +The _tep_find_common_field()_ function searches for a common field with _name_
> +in the _event_.
> +
> +The _tep_find_field()_ function searches for an event specific field with
> +_name_ in the _event_.
> +
> +The _tep_find_any_field()_ function searches for any field with _name_ in the
> +_event_.
> +
I would state also how these fields can be used. Something like:
"The field returned can then be used to find the field content from
within a data record."
> +RETURN VALUE
> +------------
> +The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_
> +functions return a pointer to the found field, or NULL in case there is no field
> +with the requested name.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
> +...
> + struct tep_format_field *field;
> +
> + field = tep_find_common_field(event, "common_pid");
> + if (field == NULL) {
> + /* Cannot find "common_pid" common field in the event */
> + }
Perhaps add what to do with this:
pid = tep_read_number(tep, record->data + field->offset, field->size);
-- Steve
> +
> + field = tep_find_field(event, "softexpires");
> + if (field == NULL) {
> + /* Cannot find "softexpires" event specific field in the event */
> + }
> +
> + field = tep_find_any_field(event, "mode");
> + if (field == NULL) {
> + /* Cannot find "mode" field in the event */
> + }
> +...
> +--
> +
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> + Header file to include in order to have access to the library APIs.
> +*-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
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 23/46] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (21 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 22/46] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 18:36 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 24/46] tools/lib/traceevent: Man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field() Tzvetomir Stoyanov
` (23 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_get_any_field_val(), tep_get_common_field_val(),
tep_get_field_val() and tep_get_field_raw() as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-field_get_val.txt | 117 ++++++++++++++++++
1 file changed, 117 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
new file mode 100644
index 000000000000..dbb4875c49fb
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
@@ -0,0 +1,117 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_any_field_val,tep_get_common_field_val,tep_get_field_val,tep_get_field_raw - Get value of a field.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
+void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_);
+--
+
+DESCRIPTION
+-----------
+These functions can be used to find a field and retrieve its value.
+
+The _tep_get_any_field_val()_ function searches in the _record_ for a filed with
+_name_, part of the _event_. If the field is found, its value is stored in _val_.
+In case of an error, an error string is printed into _s_, if _err_ is not 0.
+
+The _tep_get_common_field_val()_ function does the same as
+_tep_get_any_field_val()_, but searches only in the common fields.
+
+The _tep_get_field_val()_ function does the same as
+_tep_get_any_field_val()_, but searches only in the event specific fields.
+
+The _tep_get_field_raw()_ function searches in the _record_ for a filed with _name_,
+part of the _event_. If the field is found, a pointer to its raw data is returned.
+The size of the data is stored in _len_. In case of an error, an error string
+is printed into _s_, if _err_ is not 0.
+
+RETURN VALUE
+------------
+The _tep_get_any_field_val()_, _tep_get_common_field_val()_ and
+_tep_get_field_val()_ functions return 0 on success, or -1 in case of an error.
+
+The _tep_get_field_raw()_ function returns a pointer to field's raw data, and
+places the length of this data in _len_. In case of an error NULL is returned.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit");
+...
+void process_record(struct tep_record *record)
+{
+ int len;
+ char *comm;
+ struct tep_event_format *event;
+ unsigned long long val;
+
+ event = tep_find_event_by_record(pevent, record);
+ if (event != NULL) {
+ if (tep_get_common_field_val(NULL, event, "common_type", record, &val, 0) == 0) {
+ /* Got the value of common type field */
+ }
+ if (tep_get_field_val(NULL, event, "pid", record, &val, 0) == 0) {
+ /* Got the value of pid specific field */
+ }
+ comm = tep_get_field_raw(NULL, event, "comm", record, &len, 0);
+ if (comm != NULL) {
+ /* Got a pointer to the comm event specific field */
+ }
+ }
+}
+--
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 23/46] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw()
2019-03-08 13:36 ` [PATCH v4 23/46] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw() Tzvetomir Stoyanov
@ 2019-03-13 18:36 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 18:36 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:31 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_get_any_field_val(), tep_get_common_field_val(),
> tep_get_field_val() and tep_get_field_raw() as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-field_get_val.txt | 117 ++++++++++++++++++
> 1 file changed, 117 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
> new file mode 100644
> index 000000000000..dbb4875c49fb
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
> @@ -0,0 +1,117 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_get_any_field_val,tep_get_common_field_val,tep_get_field_val,tep_get_field_raw - Get value of a field.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +*#include <trace-seq.h>*
> +
> +int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
> +int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
> +int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
> +void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_);
> +--
> +
> +DESCRIPTION
> +-----------
> +These functions can be used to find a field and retrieve its value.
> +
> +The _tep_get_any_field_val()_ function searches in the _record_ for a filed with
s/filed/field/
> +_name_, part of the _event_. If the field is found, its value is stored in _val_.
> +In case of an error, an error string is printed into _s_, if _err_ is not 0.
The above is worded in a confusing way. May want to make it:
"If there is an error and _err_ is not zero, then an error string is
written into _s_."
> +
> +The _tep_get_common_field_val()_ function does the same as
> +_tep_get_any_field_val()_, but searches only in the common fields.
Add "This will work for any event as all events include the common
fields".
> +
> +The _tep_get_field_val()_ function does the same as
> +_tep_get_any_field_val()_, but searches only in the event specific fields.
> +
> +The _tep_get_field_raw()_ function searches in the _record_ for a filed with _name_,
/filed/field/
> +part of the _event_. If the field is found, a pointer to its raw data is returned.
> +The size of the data is stored in _len_. In case of an error, an error string
> +is printed into _s_, if _err_ is not 0.
Change that last sentence too.
-- Steve
> +
> +RETURN VALUE
> +------------
> +The _tep_get_any_field_val()_, _tep_get_common_field_val()_ and
> +_tep_get_field_val()_ functions return 0 on success, or -1 in case of an error.
> +
> +The _tep_get_field_raw()_ function returns a pointer to field's raw data, and
> +places the length of this data in _len_. In case of an error NULL is returned.
> +
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 24/46] tools/lib/traceevent: Man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (22 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 23/46] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 25/46] tools/lib/traceevent: Man page for tep_read_number_field() Tzvetomir Stoyanov
` (22 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_print_field(), tep_print_fields(),
tep_print_num_field() and tep_print_func_field()
as part of the libtraceevent APIs.
Updated description of functions in event-parse.c
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-field_print.txt | 120 ++++++++++++++++++
1 file changed, 120 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
new file mode 100644
index 000000000000..b6dd524302f3
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
@@ -0,0 +1,120 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_print_field,tep_print_fields,tep_print_num_field,tep_print_func_field - Print the field content.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_);
+void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_);
+int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
+int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
+--
+
+DESCRIPTION
+-----------
+These functions print recorded field's data, according to the field's type.
+
+The _tep_print_field()_ function extracts from the recorded raw _data_ value of
+the _field_ and prints it into _s_, according to the field type.
+
+The _tep_print_fields()_ prints recorded values of all _event_'s fields. It
+iterates all fileds of the _event_, and calls _tep_print_field()_ for each of
+them.
+
+The _tep_print_num_field()_ function prints a numeric field with given format
+string. A search is performed in the _event_ for a field with _name_. If such
+field is found, its value is extracted from the _record_ and is printed in the
+_s_, according to the given format string _fmt_. If the argument _err_ is non-zero,
+and an error occures - it is printed in the _s_.
+
+The _tep_print_func_field()_ function prints a function field with given format
+string. A search is performed in the _event_ for a field with _name_. If such
+field is found, its value is extracted from the _record_. The value is assumed
+to be a function address, and a search is perform to find the name of this
+function. The function name (if found) and its address are printed in the _s_,
+according to the given format string _fmt_. If the argument _err_ is non-zero,
+and an error occures - it is printed in _s_.
+
+RETURN VALUE
+------------
+The _tep_print_num_field()_ and _tep_print_func_field()_ functions return 1
+on success, -1 in case of an error or 0 if the print buffer _s_ is full.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
+...
+void process_record(struct tep_record *record)
+{
+ struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid");
+
+ trace_seq_reset(&seq);
+
+ /* Print the value of "common_pid" */
+ tep_print_field(&seq, record->data, field_pid);
+
+ /* Print all fields of the "hrtimer_start" event */
+ tep_print_fields(&seq, record->data, record->size, event);
+
+ /* Print the value of "expires" field with custom format string */
+ tep_print_num_field(&seq, " timer expires in %llu ", event, "expires", record, 0);
+
+ /* Print the address and the name of "function" field with custom format string */
+ tep_print_func_field(&seq, " timer function is %s ", event, "function", record, 0);
+ }
+ ...
+--
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 25/46] tools/lib/traceevent: Man page for tep_read_number_field()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (23 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 24/46] tools/lib/traceevent: Man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 26/46] tools/lib/traceevent: Man pages for tep_event_common_fields() and tep_event_fields() Tzvetomir Stoyanov
` (21 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_read_number_field()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-field_read.txt | 80 +++++++++++++++++++
1 file changed, 80 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
new file mode 100644
index 000000000000..0c560c416ac2
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
@@ -0,0 +1,80 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_read_number_field - Reads a number from a raw data.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_);
+--
+
+DESCRIPTION
+-----------
+The _tep_read_number_field()_ function reads the value of the _field_ from the
+raw _data_ and stores it in the _value_. The function sets the _value_ according
+to the endianness of the raw data and the current machine.
+
+RETURN VALUE
+------------
+The _tep_read_number_field()_ function retunrs 0 in case of success, or -1 in
+case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start");
+...
+void process_record(struct tep_record *record)
+{
+ unsigned long long pid;
+ struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid");
+
+ if (tep_read_number_field(field_pid, record->data, &pid) != 0) {
+ /* Failed to get "common_pid" value */
+ }
+}
+...
+--
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 26/46] tools/lib/traceevent: Man pages for tep_event_common_fields() and tep_event_fields()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (24 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 25/46] tools/lib/traceevent: Man page for tep_read_number_field() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset() Tzvetomir Stoyanov
` (20 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_event_common_fields() and tep_event_fields()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-fields.txt | 99 +++++++++++++++++++
1 file changed, 99 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-fields.txt b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt
new file mode 100644
index 000000000000..e4f344046519
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt
@@ -0,0 +1,99 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_event_common_fields,tep_event_fields - Get a list of fields for an event.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_);
+struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_);
+--
+
+DESCRIPTION
+-----------
+The _tep_event_common_fields()_ function returns an array of pointers to common
+fields for the _event_. The array is allocated in the function and must be freed
+by free(). The last element of the array is NULL.
+
+The _tep_event_fields()_ function returns an array of pointers to event specific
+fields for the _event_. The array is allocated in the function and must be freed
+by free(). The last element of the array is NULL.
+
+RETURN VALUE
+------------
+Both _tep_event_common_fields()_ and _tep_event_fields()_ functions return
+an array of pointers to tep_format_field structures in case of success, or
+NULL in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+int i;
+struct tep_format_field **fields;
+struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit");
+if (event != NULL) {
+ fields = tep_event_common_fields(event);
+ if (fields != NULL) {
+ i = 0;
+ while (fields[i]) {
+ /* walk through the list of the common fields of the kvm_exit event */
+ i++;
+ }
+ free(fields);
+ }
+ fields = tep_event_fields(event);
+ if (fields != NULL) {
+ i = 0;
+ while (fields[i]) {
+ /* walk through the list of the event specific fields of the kvm_exit event */
+ i++;
+ }
+ free(fields);
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (25 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 26/46] tools/lib/traceevent: Man pages for tep_event_common_fields() and tep_event_fields() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 19:11 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 28/46] tools/lib/traceevent: Man page for tep_filter_add_filter_str() Tzvetomir Stoyanov
` (19 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-filter.txt | 85 +++++++++++++++++++
1 file changed, 85 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
new file mode 100644
index 000000000000..6335bcc10c6c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
@@ -0,0 +1,85 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_alloc,tep_filter_free,tep_filter_reset - Create / free / reset an event filter.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
+void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
+void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
+is the trace event parser context.
+
+The _tep_filter_free()_ function frees an event filter and all resources that it
+had used.
+
+The _tep_filter_reset()_ function removes all rules from an event filter and
+resets it.
+
+RETURN VALUE
+------------
+The _tep_filter_alloc()_ function returns a pointer to the newly created event
+filter, or NULL in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+if (filter == NULL) {
+ /* Failed to create the filter */
+}
+...
+tep_filter_reset(filter);
+...
+tep_filter_free(filter);
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
2019-03-08 13:36 ` [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset() Tzvetomir Stoyanov
@ 2019-03-13 19:11 ` Steven Rostedt
2019-03-13 19:13 ` Steven Rostedt
0 siblings, 1 reply; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 19:11 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:35 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../Documentation/libtraceevent-filter.txt | 85 +++++++++++++++++++
> 1 file changed, 85 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> new file mode 100644
> index 000000000000..6335bcc10c6c
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> @@ -0,0 +1,85 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_filter_alloc,tep_filter_free,tep_filter_reset - Create / free / reset an event filter.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
> +void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
> +void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
> +is the trace event parser context.
We need more description on what a filter is. Hmm, perhaps we should
make all the filter functions in one man page. This way the one man
page can show how filters are used.
That is, combine this patch with the next 4 patches.
-- Steve
> +
> +The _tep_filter_free()_ function frees an event filter and all resources that it
> +had used.
> +
> +The _tep_filter_reset()_ function removes all rules from an event filter and
> +resets it.
> +
> +RETURN VALUE
> +------------
> +The _tep_filter_alloc()_ function returns a pointer to the newly created event
> +filter, or NULL in case of an error.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +struct tep_event_filter *filter = tep_filter_alloc(tep);
> +if (filter == NULL) {
> + /* Failed to create the filter */
> +}
> +...
> +tep_filter_reset(filter);
> +...
> +tep_filter_free(filter);
> +...
> +--
> +
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> + Header file to include in order to have access to the library APIs.
> +*-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
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
2019-03-13 19:11 ` Steven Rostedt
@ 2019-03-13 19:13 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 19:13 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Wed, 13 Mar 2019 15:11:27 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:
> We need more description on what a filter is. Hmm, perhaps we should
> make all the filter functions in one man page. This way the one man
> page can show how filters are used.
>
> That is, combine this patch with the next 4 patches.
Make that the next 5 patches.
-- Steve
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 28/46] tools/lib/traceevent: Man page for tep_filter_add_filter_str()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (26 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 29/46] tools/lib/traceevent: Man page for tep_filter_strerror() Tzvetomir Stoyanov
` (18 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_filter_add_filter_str()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_add.txt | 78 +++++++++++++++++++
1 file changed, 78 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
new file mode 100644
index 000000000000..5b8f67e406b2
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_add_filter_str - Adds a new rule to a filter.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The
+_filter_str_ argument is the filter string, that contains the rule.
+
+RETURN VALUE
+------------
+The _tep_filter_add_filter_str()_ function returns 0 if the rule was
+successfully added or a negative error code. Use _tep_filter_strerror()_ to see
+actual error message in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+...
+int ret;
+char errstr[200];
+ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
+if(ret < 0) {
+ tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
+ /* Failed to add a new rule to the filter, the error string is in errstr */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-ltraceevent*
+ Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_, _tep_filter_strerror(3)_
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 29/46] tools/lib/traceevent: Man page for tep_filter_strerror()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (27 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 28/46] tools/lib/traceevent: Man page for tep_filter_add_filter_str() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 30/46] tools/lib/traceevent: Man pages for tep_event_filtered() and tep_filter_remove_event() Tzvetomir Stoyanov
` (17 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_filter_strerror()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_error.txt | 78 +++++++++++++++++++
1 file changed, 78 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
new file mode 100644
index 000000000000..57bd19ad5d53
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_strerror - Fills the filter error message in a buffer.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_strerror()_ function copies the _filter_ error buffer into the
+given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_
+is copied a string, describing the error _err_.
+
+RETURN VALUE
+------------
+The _tep_filter_strerror()_ function returns 0 if message was filled
+successfully, or -1 in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+...
+int ret;
+char errstr[200];
+ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
+if(ret < 0) {
+ tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
+ /* Failed to add a new rule to the filter, the error string is in errstr */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 30/46] tools/lib/traceevent: Man pages for tep_event_filtered() and tep_filter_remove_event()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (28 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 29/46] tools/lib/traceevent: Man page for tep_filter_strerror() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 31/46] tools/lib/traceevent: Man page for tep_filter_match() Tzvetomir Stoyanov
` (16 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_event_filtered() and tep_filter_remove_event()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_event.txt | 84 +++++++++++++++++++
1 file changed, 84 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
new file mode 100644
index 000000000000..9d73e6ec8511
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
@@ -0,0 +1,84 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_event_filtered,tep_filter_remove_event - Checks / removes a filter on an event.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+--
+
+DESCRIPTION
+-----------
+The _tep_event_filtered()_ function checks if the event with _event_id_ has
+_filter_.
+
+The _tep_filter_remove_event()_ function removes a _filter_ for an event with
+_event_id_.
+
+RETURN VALUE
+------------
+The _tep_event_filtered()_ function returns 1 if the filter is found for given
+event, or 0 otherwise.
+
+The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or
+0 if the event was not found.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+...
+if (tep_event_filtered(filter, 1857) == 1) {
+ /* Event 1857 has filter */
+}
+
+if (tep_filter_remove_event(filter, 1857) == 1) {
+ /* Event 1857 was removed from the filter */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 31/46] tools/lib/traceevent: Man page for tep_filter_match()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (29 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 30/46] tools/lib/traceevent: Man pages for tep_event_filtered() and tep_filter_remove_event() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 32/46] tools/lib/traceevent: Man pages for tep_filter_copy() and tep_filter_compare() Tzvetomir Stoyanov
` (15 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_filter_match()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_match.txt | 96 +++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
new file mode 100644
index 000000000000..af5e6d2a5986
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
@@ -0,0 +1,96 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_match - Tests if a record matches a filter.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_match()_ function tests if a _record_ matches given _filter_.
+
+RETURN VALUE
+------------
+The _tep_filter_match()_ function returns _tep_errno_, according to the result:
+[verse]
+--
+_pass:[TEP_ERRNO__FILTER_MATCH]_ - filter found for event, the record matches.
+_pass:[TEP_ERRNO__FILTER_MISS]_ - filter found for event, the record does not match.
+_pass:[TEP_ERRNO__FILTER_NOT_FOUND]_ - no filter found for record's event.
+_pass:[TEP_ERRNO__NO_FILTER]_ - no rules in the filter.
+--
+or any other _tep_errno_, if an error occurred during the test.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+...
+void process_record(struct tep_record *record)
+{
+ switch (tep_filter_match(filter, record)) {
+ case TEP_ERRNO__FILTER_MATCH:
+ /* The filter matches the record */
+ break;
+ case TEP_ERRNO__FILTER_MISS:
+ /* The filter does not match the record */
+ break;
+ case TEP_ERRNO__FILTER_NOT_FOUND:
+ /* No filter found for record's event */
+ break;
+ case TEP_ERRNO__NO_FILTER:
+ /* There are no rules in the filter */
+ break
+ default:
+ /* An error occurred during the test */
+ break;
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 32/46] tools/lib/traceevent: Man pages for tep_filter_copy() and tep_filter_compare()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (30 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 31/46] tools/lib/traceevent: Man page for tep_filter_match() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 33/46] tools/lib/traceevent: Man page for tep_filter_make_string() Tzvetomir Stoyanov
` (14 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_filter_copy() and tep_filter_compare()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_oper.txt | 84 +++++++++++++++++++
1 file changed, 84 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
new file mode 100644
index 000000000000..dce4cc649ad0
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
@@ -0,0 +1,84 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_copy,tep_filter_compare - Copy / compare operations with event filters.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
+int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter.
+
+The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_.
+
+RETURN VALUE
+------------
+The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules
+ were copied.
+
+The _tep_filter_compare()_ function returns 1 if the two filters hold the same
+content, or 0 if they do not.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_event_filter *filter1 = tep_filter_alloc(tep);
+struct tep_event_filter *filter2 = tep_filter_alloc(tep);
+...
+if (tep_filter_copy(filter1, filter2) != 0) {
+ /* Failed to copy filter2 in filter1 */
+}
+...
+if (tep_filter_compare(filter1, filter2) != 1) {
+ /* Both filters are different */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 33/46] tools/lib/traceevent: Man page for tep_filter_make_string()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (31 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 32/46] tools/lib/traceevent: Man pages for tep_filter_copy() and tep_filter_compare() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial() Tzvetomir Stoyanov
` (13 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_filter_make_string()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_show.txt | 75 +++++++++++++++++++
1 file changed, 75 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
new file mode 100644
index 000000000000..8d54b401018e
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
@@ -0,0 +1,75 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_make_string - Returns a string showing the filter.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_make_string()_ function constructs a string, displaying
+the _filter_ contents for given _event_id_.
+
+RETURN VALUE
+------------
+The _tep_filter_make_string()_ function returns a string, which must be freed
+with free(), or NULL in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter = tep_filter_alloc(tep);
+...
+char *fstring = tep_filter_make_string(filter, 352);
+if (fstring != NULL) {
+ /* The filter for event 352 is in fstring */
+ free(fstring);
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (32 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 33/46] tools/lib/traceevent: Man page for tep_filter_make_string() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 20:04 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 35/46] tools/lib/traceevent: Man pages for tep_find_function() and tep_find_function_address() Tzvetomir Stoyanov
` (12 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_filter_event_has_trivial(),
tep_update_trivial() and tep_filter_clear_trivial()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-filter_trivial.txt | 112 ++++++++++++++++++
1 file changed, 112 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
new file mode 100644
index 000000000000..7114192d3640
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
@@ -0,0 +1,112 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_filter_event_has_trivial,tep_update_trivial,tep_filter_clear_trivial - Check / update / clear trivial rules of given filter.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_filter_trivial_type* {
+ _TEP_FILTER_TRIVIAL_FALSE_,
+ _TEP_FILTER_TRIVIAL_TRUE_,
+ _TEP_FILTER_TRIVIAL_BOTH_,
+};
+
+int *tep_filter_event_has_trivial*(struct tep_event_filter pass:[*]_filter_, int _event_id_, enum tep_filter_trivial_type _type_);
+int *tep_update_trivial*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_, enum tep_filter_trivial_type _type_);
+int *tep_filter_clear_trivial*(struct tep_event_filter pass:[*]_filter_, enum tep_filter_trivial_type _type_);
+--
+
+DESCRIPTION
+-----------
+The _tep_filter_event_has_trivial()_ function checks if the event with
+_event_id_ contains a trivial _filter_ of _type_.
+
+The _tep_update_trivial()_ function updates the trivial rules with the given
+filter. It scans _dest_ for trivial events matching _type_ to replace with
+the _source_.
+
+The _tep_filter_clear_trivial()_ function clears TRUE and FALSE rules.
+It removes rules in the _filter_ that only contain a given _type_ boolean arg.
+
+The trivial _type_, used as argument of these functions can be:
+[verse]
+--
+ _TEP_FILTER_TRIVIAL_FALSE_ - TRUE
+ _TEP_FILTER_TRIVIAL_TRUE_ - FALSE
+ _TEP_FILTER_TRIVIAL_BOTH_ - TRUE or FALSE
+
+--
+
+RETURN VALUE
+------------
+The _tep_filter_event_has_trivial()_ function returns 1 if the event contains
+a matching trivial type, otherwise 0.
+
+The _tep_update_trivial()_ function returns 0 on success, or -1 if there was
+a problem updating, but events may have still been updated on error.
+
+The _tep_filter_clear_trivial()_ function returns 0 on success, or -1 if there
+was a problem.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct tep_event_filter *filter1 = tep_filter_alloc(tep);
+struct tep_event_filter *filter2 = tep_filter_alloc(tep);
+...
+if (tep_filter_event_has_trivial(filter1, 1857,TEP_FILTER_TRIVIAL_FALSE) == 0) {
+ /* There are FALSE rules in filer1 for the event 1857 */
+}
+
+if (tep_update_trivial(filter1, filter2, TEP_FILTER_TRIVIAL_TRUE) != 0) {
+ /* Failed to update TRUE trivial rules of filter1 with filter2 */
+}
+
+if (tep_filter_clear_trivial(filter, TEP_FILTER_TRIVIAL_BOTH) == 0) {
+ /* Failed to clear TRUE and FALSE trivial rules of filter1 */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial()
2019-03-08 13:36 ` [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial() Tzvetomir Stoyanov
@ 2019-03-13 20:04 ` Steven Rostedt
2019-03-15 12:26 ` Tzvetomir Stoyanov
0 siblings, 1 reply; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 20:04 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:42 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_filter_event_has_trivial(),
> tep_update_trivial() and tep_filter_clear_trivial()
> as part of the libtraceevent APIs.
Hmm, the trivial filter logic was an optimization of the old
kernelshark and isn't used today. I think the best course of action is
to delete the trivial filter APIs.
-- Steve
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial()
2019-03-13 20:04 ` Steven Rostedt
@ 2019-03-15 12:26 ` Tzvetomir Stoyanov
0 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-15 12:26 UTC (permalink / raw)
To: Steven Rostedt; +Cc: linux-trace-devel
On Wed, Mar 13, 2019 at 10:04 PM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Fri, 8 Mar 2019 15:36:42 +0200
> Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> > Create man pages for tep_filter_event_has_trivial(),
> > tep_update_trivial() and tep_filter_clear_trivial()
> > as part of the libtraceevent APIs.
>
> Hmm, the trivial filter logic was an optimization of the old
> kernelshark and isn't used today. I think the best course of action is
> to delete the trivial filter APIs.
>
I'll remove man pages related to the trivial filter API from the patchset.
> -- Steve
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 35/46] tools/lib/traceevent: Man pages for tep_find_function() and tep_find_function_address()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (33 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 34/46] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 20:05 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 36/46] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver() Tzvetomir Stoyanov
` (11 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_find_function() and tep_find_function_address()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-func_find.txt | 88 +++++++++++++++++++
1 file changed, 88 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
new file mode 100644
index 000000000000..04840e244445
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
@@ -0,0 +1,88 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_find_function,tep_find_function_address - Find function name / start address.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
+unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
+--
+
+DESCRIPTION
+-----------
+These functions can be used to find function name and start address, by given
+address. The given address does not have to be exact, it will select the function
+that would contain it.
+
+The _tep_find_function()_ function returns the function name, which contains the
+given address _addr_. The _tep_ argument is the trace event parser context.
+
+The _tep_find_function_address()_ function returns the function start address,
+by given address _addr_. The _addr_ does not have to be exact, it will select the
+function that would contain it. The _tep_ argument is the trace event parser context.
+
+RETURN VALUE
+------------
+The _tep_find_function()_ function returns the function name, or NULL in case
+it cannot be found.
+
+The _tep_find_function_address()_ function returns the function start address,
+or 0 in case it cannot be found.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+void show_function( unsigned long long addr)
+{
+ const char *fname = tep_find_function(tep, addr);
+ unsigned long long fstart = tep_find_function_address(tep, addr);
+
+ /* addr is in function named fname, starting at fstart address, at offset (addr - fstart) */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 36/46] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (34 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 35/46] tools/lib/traceevent: Man pages for tep_find_function() and tep_find_function_address() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 20:06 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 37/46] tools/lib/traceevent: Man pages for tep_parse_event() and tep_parse_format() Tzvetomir Stoyanov
` (10 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_set_function_resolver() and tep_reset_function_resolver()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-func_resolve.txt | 96 +++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
new file mode 100644
index 000000000000..38b715bd926c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
@@ -0,0 +1,96 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_function_resolver,tep_reset_function_resolver - Set / reset an alternative function resolver
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_);
+
+int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
+void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
+--
+
+DESCRIPTION
+-----------
+Some tools may have already a way to resolve the kernel functions. These APIs
+allow them to keep using it instead of duplicating all the entries inside.
+
+The _tep_set_function_resolver()_ function registers _func_ as an alternative
+kernel functions resolver. The _tep_ argument is trace event parser context.
+The _priv_ argument is a custom context of the _func_ function.
+
+The _tep_reset_function_resolver()_ function resets the kernel functions
+resolver to the default function. The _tep_ argument is trace event parser
+context.
+
+The _tep_func_resolver_t_ type is the prototype of the alternative kernel
+functions resolver. This function receives a pointer to its custom context
+(set with the _tep_set_function_resolver()_ call ) and the address of a kernel
+function, which has to be resolved. In case of success, it should return
+the name of the function and its module (if any) in _modp_.
+
+RETURN VALUE
+------------
+The _tep_set_function_resolver()_ function returns 0 in case of success, or -1
+in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+char *my_resolve_kernel_addr(void *context, unsigned long long *addrp, char **modp)
+{
+ return NULL;
+}
+...
+ if (tep_set_function_resolver(tep, my_resolve_kernel_addr, NULL) != 0) {
+ /* failed to register my_resolve_kernel_addr */
+ }
+...
+ tep_reset_function_resolver(tep);
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 37/46] tools/lib/traceevent: Man pages for tep_parse_event() and tep_parse_format()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (35 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 36/46] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 38/46] tools/lib/traceevent: Man page for tep_parse_header_page() Tzvetomir Stoyanov
` (9 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_parse_event() and tep_parse_format()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-parse_event.txt | 90 +++++++++++++++++++
1 file changed, 90 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
new file mode 100644
index 000000000000..64c9f0df58aa
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
@@ -0,0 +1,90 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_parse_event,tep_parse_format - Parse the event format information
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);
+enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);
+--
+
+DESCRIPTION
+-----------
+The _tep_parse_event()_ function parses the event format and creates an event
+structure to quickly parse raw data for a given event. The _tep_ argument is
+the trace event parser context. The created event structure is stored in the
+_tep_ context. The _buf_ argument is a buffer with _size_, where the event
+format data is. The event format data can be taken from
+tracefs/events/.../.../format files. The _sys_ argument is the system of
+the event.
+
+The _tep_parse_format()_ function does the same as _tep_parse_event()_. The only
+difference is in the extra _eventp_ argument, where the newly created event
+structure is returned.
+
+RETURN VALUE
+------------
+Both _tep_parse_event()_ and _tep_parse_format()_ functions return 0 on success,
+or TEP_ERRNO__... in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+char *buf;
+int size;
+struct tep_event *event = NULL;
+buf = read_file("/sys/kernel/tracing/events/ftrace/print/format", &size);
+if (tep_parse_event(tep, buf, size, "ftrace") != 0) {
+ /* Failed to parse the ftrace print format */
+}
+
+if (tep_parse_format(tep, &event, buf, size, "ftrace") != 0) {
+ /* Failed to parse the ftrace print format */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 38/46] tools/lib/traceevent: Man page for tep_parse_header_page()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (36 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 37/46] tools/lib/traceevent: Man pages for tep_parse_event() and tep_parse_format() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin() Tzvetomir Stoyanov
` (8 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_parse_header_page()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-parse_head.txt | 82 +++++++++++++++++++
1 file changed, 82 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
new file mode 100644
index 000000000000..c90f16c7d8e6
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
@@ -0,0 +1,82 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_parse_header_page - Parses the data stored in the header page.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_parse_header_page()_ function parses the header page data from _buf_,
+and initializes the _tep_, trace event parser context, with it. The buffer
+_buf_ is with _size_, and is supposed to be copied from
+tracefs/events/header_page.
+
+Some old kernels do not have header page info, in this case the
+_tep_parse_header_page()_ function can be called with _size_ equal to 0. The
+_tep_ context is initialized with default values. The _long_size_ can be used in
+this use case, to set the size of a long integer to be used.
+
+RETURN VALUE
+------------
+The _tep_parse_header_page()_ function returns 0 in case of success, or -1
+in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+char *buf;
+int size;
+buf = read_file("/sys/kernel/tracing/events/header_page", &size);
+if (tep_parse_header_page(tep, buf, size, sizeof(unsigned long)) != 0) {
+ /* Failed to parse the header page */
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (37 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 38/46] tools/lib/traceevent: Man page for tep_parse_header_page() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 20:27 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt() Tzvetomir Stoyanov
` (7 subsequent siblings)
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_load_plugins() and tep_unload_plugin()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-plugins.txt | 98 +++++++++++++++++++
1 file changed, 98 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
new file mode 100644
index 000000000000..0f40d14944c0
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
@@ -0,0 +1,98 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_load_plugins,tep_unload_plugins - Load / unload traceevent plugins
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_);
+void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_);
+--
+
+DESCRIPTION
+-----------
+The _tep_load_plugins()_ function loads all plugins, located in the plugin
+directories. The _tep_ argument is trace event parser context.
+The plugin directories are :
+[verse]
+--
+ - System's plugin directory, defined at the library compile time. It
+ depends on the library installation prefix and usually is
+ _(install_preffix)/lib/traceevent/plugins_
+ - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_
+ - User's plugin directory, located at _~/.traceevent/plugins_
+--
+Loading of plugins can be controlled by the _tep_flags_, using the
+_tep_set_flag()_ API:
+[verse]
+--
+ _TEP_DISABLE_SYS_PLUGINS_ - do not load plugins, located in
+ the system's plugin directory.
+ _TEP_DISABLE_PLUGINS_ - do not load any plugins.
+--
+The _tep_set_flag()_ API must be called before _tep_load_plugins()_.
+
+The _tep_unload_plugins()_ function unloads the plugins, previously loaded by
+_tep_load_plugins()_. The _tep_ argument is trace event parser context. The
+_plugin_list_ is the list of loaded plugins, returned by the _tep_load_plugins()_
+function.
+
+RETURN VALUE
+------------
+The _tep_load_plugins()_ function returns a list of successfully loaded plugins,
+or NULL in case no plugins are loaded.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+struct tep_plugin_list *plugins = tep_load_plugins(tep);
+if (plugins == NULL) {
+ /* no plugins are loaded */
+}
+...
+tep_unload_plugins(plugins, tep);
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-ltraceevent*
+ Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_, _tep_set_flag(3)_
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()
2019-03-08 13:36 ` [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin() Tzvetomir Stoyanov
@ 2019-03-13 20:27 ` Steven Rostedt
2019-03-13 21:42 ` Patrick McLean
0 siblings, 1 reply; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 20:27 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel, Patrick McLean
On Fri, 8 Mar 2019 15:36:47 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man pages for tep_load_plugins() and tep_unload_plugin()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../Documentation/libtraceevent-plugins.txt | 98 +++++++++++++++++++
> 1 file changed, 98 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> new file mode 100644
> index 000000000000..0f40d14944c0
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> @@ -0,0 +1,98 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_load_plugins,tep_unload_plugins - Load / unload traceevent plugins
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_);
> +void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_);
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_load_plugins()_ function loads all plugins, located in the plugin
> +directories. The _tep_ argument is trace event parser context.
> +The plugin directories are :
> +[verse]
> +--
> + - System's plugin directory, defined at the library compile time. It
> + depends on the library installation prefix and usually is
> + _(install_preffix)/lib/traceevent/plugins_
> + - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_
> + - User's plugin directory, located at _~/.traceevent/plugins_
We are going to need to modify this to be more compliant with today's
desktops.
Patrick, where's the place to put customized plugins that should
overwrite the system ones?
-- Steve
> +--
> +Loading of plugins can be controlled by the _tep_flags_, using the
> +_tep_set_flag()_ API:
> +[verse]
> +--
> + _TEP_DISABLE_SYS_PLUGINS_ - do not load plugins, located in
> + the system's plugin directory.
> + _TEP_DISABLE_PLUGINS_ - do not load any plugins.
> +--
> +The _tep_set_flag()_ API must be called before _tep_load_plugins()_.
> +
> +The _tep_unload_plugins()_ function unloads the plugins, previously loaded by
> +_tep_load_plugins()_. The _tep_ argument is trace event parser context. The
> +_plugin_list_ is the list of loaded plugins, returned by the _tep_load_plugins()_
> +function.
> +
> +RETURN VALUE
> +------------
> +The _tep_load_plugins()_ function returns a list of successfully loaded plugins,
> +or NULL in case no plugins are loaded.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +struct tep_plugin_list *plugins = tep_load_plugins(tep);
> +if (plugins == NULL) {
> + /* no plugins are loaded */
> +}
> +...
> +tep_unload_plugins(plugins, tep);
> +--
> +
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> + Header file to include in order to have access to the library APIs.
> +*-ltraceevent*
> + Linker switch to add when building a program that uses the library.
> +--
> +
> +SEE ALSO
> +--------
> +_libtraceevent(3)_, _trace-cmd(1)_, _tep_set_flag(3)_
> +
> +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
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()
2019-03-13 20:27 ` Steven Rostedt
@ 2019-03-13 21:42 ` Patrick McLean
2019-03-13 21:45 ` Patrick McLean
0 siblings, 1 reply; 80+ messages in thread
From: Patrick McLean @ 2019-03-13 21:42 UTC (permalink / raw)
To: Steven Rostedt; +Cc: Tzvetomir Stoyanov, linux-trace-devel
On Wed, 13 Mar 2019 16:27:56 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:
> On Fri, 8 Mar 2019 15:36:47 +0200
> Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> > Create man pages for tep_load_plugins() and tep_unload_plugin()
> > as part of the libtraceevent APIs.
> >
> > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> > ---
> > .../Documentation/libtraceevent-plugins.txt | 98
> > +++++++++++++++++++ 1 file changed, 98 insertions(+)
> > create mode 100644
> > tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> >
> > diff --git
> > a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt new
> > file mode 100644 index 000000000000..0f40d14944c0 --- /dev/null
> > +++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > @@ -0,0 +1,98 @@
> > +libtraceevent(3)
> > +================
> > +
> > +NAME
> > +----
> > +tep_load_plugins,tep_unload_plugins - Load / unload traceevent
> > plugins +
> > +SYNOPSIS
> > +--------
> > +[verse]
> > +--
> > +*#include <event-parse.h>*
> > +
> > +struct tep_plugin_list pass:[*]*tep_load_plugins*(struct
> > tep_handle pass:[*]_tep_); +void *tep_unload_plugins*(struct
> > tep_plugin_list pass:[*]_plugin_list_, struct tep_handle
> > pass:[*]_tep_); +-- +
> > +DESCRIPTION
> > +-----------
> > +The _tep_load_plugins()_ function loads all plugins, located in
> > the plugin +directories. The _tep_ argument is trace event parser
> > context. +The plugin directories are :
> > +[verse]
> > +--
> > + - System's plugin directory, defined at the library
> > compile time. It
> > + depends on the library installation prefix and usually is
> > + _(install_preffix)/lib/traceevent/plugins_
> > + - Directory, defined by the environment variable
> > _TRACEEVENT_PLUGIN_DIR_
> > + - User's plugin directory, located at
> > _~/.traceevent/plugins_
>
> We are going to need to modify this to be more compliant with today's
> desktops.
>
> Patrick, where's the place to put customized plugins that should
> overwrite the system ones?
>
That sort of depends, if they are textual and could be considered
configs, then .config is where they should go, otherwise
${HOME}/.local/share/traceevent or ${HOME}/.local/lib/traceevent,
binaries should go under the lib, arch agnostic stuff should go under
share.
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()
2019-03-13 21:42 ` Patrick McLean
@ 2019-03-13 21:45 ` Patrick McLean
2019-03-14 0:53 ` Steven Rostedt
0 siblings, 1 reply; 80+ messages in thread
From: Patrick McLean @ 2019-03-13 21:45 UTC (permalink / raw)
To: Steven Rostedt; +Cc: Tzvetomir Stoyanov, linux-trace-devel
On Wed, 13 Mar 2019 14:42:06 -0700
Patrick McLean <chutzpah@gentoo.org> wrote:
> On Wed, 13 Mar 2019 16:27:56 -0400
> Steven Rostedt <rostedt@goodmis.org> wrote:
>
> > On Fri, 8 Mar 2019 15:36:47 +0200
> > Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> >
> > > Create man pages for tep_load_plugins() and tep_unload_plugin()
> > > as part of the libtraceevent APIs.
> > >
> > > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> > > ---
> > > .../Documentation/libtraceevent-plugins.txt | 98
> > > +++++++++++++++++++ 1 file changed, 98 insertions(+)
> > > create mode 100644
> > > tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > >
> > > diff --git
> > > a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > > b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt new
> > > file mode 100644 index 000000000000..0f40d14944c0 --- /dev/null
> > > +++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > > @@ -0,0 +1,98 @@
> > > +libtraceevent(3)
> > > +================
> > > +
> > > +NAME
> > > +----
> > > +tep_load_plugins,tep_unload_plugins - Load / unload traceevent
> > > plugins +
> > > +SYNOPSIS
> > > +--------
> > > +[verse]
> > > +--
> > > +*#include <event-parse.h>*
> > > +
> > > +struct tep_plugin_list pass:[*]*tep_load_plugins*(struct
> > > tep_handle pass:[*]_tep_); +void *tep_unload_plugins*(struct
> > > tep_plugin_list pass:[*]_plugin_list_, struct tep_handle
> > > pass:[*]_tep_); +-- +
> > > +DESCRIPTION
> > > +-----------
> > > +The _tep_load_plugins()_ function loads all plugins, located in
> > > the plugin +directories. The _tep_ argument is trace event parser
> > > context. +The plugin directories are :
> > > +[verse]
> > > +--
> > > + - System's plugin directory, defined at the library
> > > compile time. It
> > > + depends on the library installation prefix and usually
> > > is
> > > + _(install_preffix)/lib/traceevent/plugins_
> > > + - Directory, defined by the environment variable
> > > _TRACEEVENT_PLUGIN_DIR_
> > > + - User's plugin directory, located at
> > > _~/.traceevent/plugins_
> >
> > We are going to need to modify this to be more compliant with
> > today's desktops.
> >
> > Patrick, where's the place to put customized plugins that should
> > overwrite the system ones?
> >
>
> That sort of depends, if they are textual and could be considered
> configs, then .config is where they should go, otherwise
> ${HOME}/.local/share/traceevent or ${HOME}/.local/lib/traceevent,
> binaries should go under the lib, arch agnostic stuff should go under
> share.
More information on this spec here:
https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
The "${HOME}.local/lib" is not listed in the spec, but it is the
convention that is often used.
https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()
2019-03-13 21:45 ` Patrick McLean
@ 2019-03-14 0:53 ` Steven Rostedt
0 siblings, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-14 0:53 UTC (permalink / raw)
To: Patrick McLean; +Cc: Tzvetomir Stoyanov, linux-trace-devel
On Wed, 13 Mar 2019 14:45:17 -0700
Patrick McLean <chutzpah@gentoo.org> wrote:
> > > Patrick, where's the place to put customized plugins that should
> > > overwrite the system ones?
> > >
> >
> > That sort of depends, if they are textual and could be considered
> > configs, then .config is where they should go, otherwise
> > ${HOME}/.local/share/traceevent or ${HOME}/.local/lib/traceevent,
> > binaries should go under the lib, arch agnostic stuff should go under
> > share.
>
> More information on this spec here:
> https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
>
> The "${HOME}.local/lib" is not listed in the spec, but it is the
> convention that is often used.
> https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
Thanks. Note, these can be either .so binaries, or python scripts.
-- Steve
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (38 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 39/46] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-13 20:32 ` Steven Rostedt
2019-03-19 19:32 ` [Suspected Spam] " Matt Helsley
2019-03-08 13:36 ` [PATCH v4 41/46] tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags() Tzvetomir Stoyanov
` (6 subsequent siblings)
46 siblings, 2 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man page for tep_data_lat_fmt()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-record_lat.txt | 77 +++++++++++++++++++
1 file changed, 77 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
new file mode 100644
index 000000000000..f4e37b186f61
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
@@ -0,0 +1,77 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_data_lat_fmt - Parses the data for the latency format.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+void *tep_data_lat_fmt*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
+--
+DESCRIPTION
+-----------
+The _tep_data_lat_fmt()_ function parses out the latency format (interrupts
+disabled, need rescheduling, in hard/soft interrupt, preempt count and
+lock depth) from _record_ and places it into the _s_. The _tep_ argument is
+the trace event parser context.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+void process_record(struct tep_record *record)
+{
+ /* Place latency information in the seq */
+ tep_data_lat_fmt(tep, &seq, 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)_,_tep_set_latency_format(3)_
+
+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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt()
2019-03-08 13:36 ` [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt() Tzvetomir Stoyanov
@ 2019-03-13 20:32 ` Steven Rostedt
2019-03-19 19:32 ` [Suspected Spam] " Matt Helsley
1 sibling, 0 replies; 80+ messages in thread
From: Steven Rostedt @ 2019-03-13 20:32 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: linux-trace-devel
On Fri, 8 Mar 2019 15:36:48 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Create man page for tep_data_lat_fmt()
> as part of the libtraceevent APIs.
This should be included in the same man page as
tep_set_latency_format and tep_is_latency_format.
-- Steve
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-record_lat.txt | 77 +++++++++++++++++++
> 1 file changed, 77 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> new file mode 100644
> index 000000000000..f4e37b186f61
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> @@ -0,0 +1,77 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_data_lat_fmt - Parses the data for the latency format.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +void *tep_data_lat_fmt*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
> +--
> +DESCRIPTION
> +-----------
> +The _tep_data_lat_fmt()_ function parses out the latency format (interrupts
> +disabled, need rescheduling, in hard/soft interrupt, preempt count and
> +lock depth) from _record_ and places it into the _s_. The _tep_ argument is
> +the trace event parser context.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +#include <trace-seq.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +struct trace_seq seq;
> +trace_seq_init(&seq);
> +...
> +void process_record(struct tep_record *record)
> +{
> + /* Place latency information in the seq */
> + tep_data_lat_fmt(tep, &seq, 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)_,_tep_set_latency_format(3)_
> +
> +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
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [Suspected Spam] [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt()
2019-03-08 13:36 ` [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt() Tzvetomir Stoyanov
2019-03-13 20:32 ` Steven Rostedt
@ 2019-03-19 19:32 ` Matt Helsley
1 sibling, 0 replies; 80+ messages in thread
From: Matt Helsley @ 2019-03-19 19:32 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: rostedt, linux-trace-devel
> On Mar 8, 2019, at 5:36 AM, Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> Create man page for tep_data_lat_fmt()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
> .../libtraceevent-record_lat.txt | 77 +++++++++++++++++++
> 1 file changed, 77 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> new file mode 100644
> index 000000000000..f4e37b186f61
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> @@ -0,0 +1,77 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_data_lat_fmt - Parses the data for the latency format.
It’s not exactly an issue with this man page but I notice that, unlike a sampling of libtraceevent API function names in this series, this one is quite abbreviated. Is it called very often? Would it make sense to rename it to be as clear as the other function names?
tep_data_latency_format
seems much clearer to me.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +void *tep_data_lat_fmt*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
> +--
> +DESCRIPTION
> +-----------
> +The _tep_data_lat_fmt()_ function parses out the latency format (interrupts
> +disabled, need rescheduling, in hard/soft interrupt, preempt count and
> +lock depth) from _record_ and places it into the _s_. The _tep_ argument is
> +the trace event parser context.
This one is missing the RETURN VALUE section.
Cheers,
-Matt
^ permalink raw reply [flat|nested] 80+ messages in thread
* [PATCH v4 41/46] tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (39 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 40/46] tools/lib/traceevent: Man page for tep_data_lat_fmt() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 42/46] tools/lib/traceevent: Man pages for trace_seq_init() and trace_seq_destroy() Tzvetomir Stoyanov
` (5 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for tep_data_type(), tep_data_pid(),
tep_data_preempt_count() and tep_data_flags()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-record_parse.txt | 134 ++++++++++++++++++
1 file changed, 134 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
new file mode 100644
index 000000000000..a74581d5c668
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
@@ -0,0 +1,134 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_data_type,tep_data_pid,tep_data_preempt_count,tep_data_flags - Extract common fields from a record.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *trace_flag_type* {
+ _TRACE_FLAG_IRQS_OFF_,
+ _TRACE_FLAG_IRQS_NOSUPPOR_,
+ _TRACE_FLAG_NEED_RESCHED_,
+ _TRACE_FLAG_HARDIRQ_,
+ _TRACE_FLAG_SOFTIRQ_,
+};
+
+int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+--
+
+DESCRIPTION
+-----------
+This set of functions can be used to extract common fields from a record.
+
+The _tep_data_type()_ function gets the event id from the record _rec_. It reads
+the "common_type" field. The _tep_ argument is the trace event parser context.
+
+The _tep_data_pid()_ function gets the process id from the record _rec_. It reads
+the "common_pid" field. The _tep_ argument is the trace event parser context.
+
+The _tep_data_preempt_count()_ function gets the preemption count from the record
+_rec_. It reads the "common_preempt_count" field. The _tep_ argument is the
+trace event parser context.
+
+The _tep_data_flags()_ function gets the latency flags from the record _rec_.
+It reads the "common_flags" field. The _tep_ argument is the trace event parser
+context. Supported latency flags are:
+[verse]
+--
+ _TRACE_FLAG_IRQS_OFF_, Interrupts are disabled.
+ _TRACE_FLAG_IRQS_NOSUPPOR_, Reading IRQ flag is not supported by the architecture.
+ _TRACE_FLAG_NEED_RESCHED_, Task needs rescheduling.
+ _TRACE_FLAG_HARDIRQ_, Hard IRQ is running.
+ _TRACE_FLAG_SOFTIRQ_, Soft IRQ is running.
+--
+
+RETURN VALUE
+------------
+The _tep_data_type()_ function returns an integer, representing the event id.
+
+The _tep_data_pid()_ function returns an integer, representing the process id
+
+The _tep_data_preempt_count()_ function returns an integer, representing the
+preemption count.
+
+The _tep_data_flags()_ function returns an integer, representing the latency
+flags. Look at the _trace_flag_type_ enum for supported flags.
+
+All these functions in case of an error return a negative integer.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+void process_record(struct tep_record *record)
+{
+ int data;
+
+ data = tep_data_type(tep, record);
+ if (data >= 0) {
+ /* Got the ID of the event */
+ }
+
+ data = tep_data_pid(tep, record);
+ if (data >= 0) {
+ /* Got the process ID */
+ }
+
+ data = tep_data_preempt_count(tep, record);
+ if (data >= 0) {
+ /* Got the preemption count */
+ }
+
+ data = tep_data_flags(tep, record);
+ if (data >= 0) {
+ /* Got the latency flags */
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 42/46] tools/lib/traceevent: Man pages for trace_seq_init() and trace_seq_destroy()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (40 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 41/46] tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 43/46] tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and trace_seq_do_printf() Tzvetomir Stoyanov
` (4 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for trace_seq_init() and trace_seq_destroy()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-tseq.txt | 76 +++++++++++++++++++
1 file changed, 76 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
new file mode 100644
index 000000000000..d11732c460ba
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
@@ -0,0 +1,76 @@
+libtraceevent(3)
+================
+
+NAME
+----
+trace_seq_init,trace_seq_destroy - Initialize / destroy a trace sequence.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+void *trace_seq_init*(struct trace_seq pass:[*]_s_);
+void *trace_seq_destroy*(struct trace_seq pass:[*]_s_);
+--
+
+DESCRIPTION
+-----------
+Trace sequences are used to allow a function to call several other functions
+to create a string of data to use.
+
+The _trace_seq_init()_ function initializes the trace sequence _s_.
+
+The _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees
+all its resources that it had used.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+trace_seq_destroy(&seq);
+...
+--
+
+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.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 43/46] tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and trace_seq_do_printf()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (41 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 42/46] tools/lib/traceevent: Man pages for trace_seq_init() and trace_seq_destroy() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 44/46] tools/lib/traceevent: Man pages for trace_seq_printf() and trace_seq_vprintf() Tzvetomir Stoyanov
` (3 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for trace_seq_do_fprintf() and trace_seq_do_printf()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-tseq_doprint.txt | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
new file mode 100644
index 000000000000..dd46a7e05c4f
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
@@ -0,0 +1,89 @@
+libtraceevent(3)
+================
+
+NAME
+----
+trace_seq_do_fprintf,trace_seq_do_printf - Print the trace sequence buffer to a file.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_);
+int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_);
+--
+
+DESCRIPTION
+-----------
+Trace sequences are used to allow a function to call several other functions
+to create a string of data to use.
+
+The _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to
+the standard output stdout.
+
+The _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_
+to the given file _fp_.
+
+RETURN VALUE
+------------
+Both _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the
+number of printed characters, or -1 in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+if (trace_seq_do_printf(&seq) < 0 ) [
+ /* Failed to print the buffer of the trace sequence to the standard output */
+}
+...
+FILE *fp = fopen("trace.txt", "w");
+if (trace_seq_do_fprintf(&seq, fp) < 0 ) [
+ /* Failed to print the buffer of the trace sequence to the trace.txt file */
+}
+...
+--
+
+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.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 44/46] tools/lib/traceevent: Man pages for trace_seq_printf() and trace_seq_vprintf()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (42 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 43/46] tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and trace_seq_do_printf() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 13:36 ` [PATCH v4 45/46] tools/lib/traceevent: Man pages for trace_seq_putc() and trace_seq_puts() Tzvetomir Stoyanov
` (2 subsequent siblings)
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for trace_seq_printf() and trace_seq_vprintf()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-tseq_print.txt | 96 +++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
new file mode 100644
index 000000000000..f0919bcf1fe3
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
@@ -0,0 +1,96 @@
+libtraceevent(3)
+================
+
+NAME
+----
+trace_seq_printf,trace_seq_vprintf - Print formated string with arguments in a trace sequence.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._);
+int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_);
+--
+
+DESCRIPTION
+-----------
+Trace sequences are used to allow a function to call several other functions
+to create a string of data to use.
+
+The _trace_seq_printf()_ function puts a formated string _fmt _with
+variable arguments _..._ in the trace sequence _s_.
+
+The _trace_seq_vprintf()_ function puts a formated string _fmt _with
+list of arguments _args_ in the trace sequence _s_.
+
+RETURN VALUE
+------------
+
+Both _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return 0 if the
+trace oversizes the buffer's free space, the number of characters printed, or
+a negative value in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+if (trace_seq_printf(&seq, "example print %d", 10) <= 0) {
+ /* Failed to print in the trace sequence */
+}
+...
+void my_print(char *format, ...)
+{
+ va_list ap;
+ va_start(ap, format);
+ if (trace_seq_printf(&seq, format, ap) <= 0) {
+ /* Failed to print in the trace sequence */
+ }
+ va_end(ap);
+}
+...
+--
+
+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.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 45/46] tools/lib/traceevent: Man pages for trace_seq_putc() and trace_seq_puts()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (43 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 44/46] tools/lib/traceevent: Man pages for trace_seq_printf() and trace_seq_vprintf() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-14 2:58 ` Steven Rostedt
2019-03-08 13:36 ` [PATCH v4 46/46] tools/lib/traceevent: Man pages for trace_seq_reset() and trace_seq_terminate() Tzvetomir Stoyanov
2019-03-08 14:19 ` [PATCH v4 00/46] Libtraceevent MAN pages Claudio
46 siblings, 1 reply; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for trace_seq_putc() and trace_seq_puts()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../Documentation/libtraceevent-tseq_put.txt | 89 +++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
new file mode 100644
index 000000000000..d14d7791d0ef
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
@@ -0,0 +1,89 @@
+libtraceevent(3)
+================
+
+NAME
+----
+trace_seq_putc,trace_seq_puts - Put string / character in a trace sequence.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_);
+int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_);
+--
+
+DESCRIPTION
+-----------
+Trace sequences are used to allow a function to call several other functions
+to create a string of data to use.
+
+The _trace_seq_putc()_ function puts a single character _c_ in the trace
+sequence _s_.
+
+The _trace_seq_puts()_ function puts a NULL terminated string _str_ in the
+trace sequence _s_.
+
+RETURN VALUE
+------------
+Both _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of
+characters put in the trace sequence, or 0 in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+if (trace_seq_putc(&seq, ';') != 1) {
+ /* Failed to put ';' in the trace sequence */
+}
+...
+char *str = " foo ";
+if (trace_seq_puts(&seq, str) != strlen(str)) {
+ /* Failed to put " foo " in the trace sequence */
+}
+...
+--
+
+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.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* [PATCH v4 46/46] tools/lib/traceevent: Man pages for trace_seq_reset() and trace_seq_terminate()
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (44 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 45/46] tools/lib/traceevent: Man pages for trace_seq_putc() and trace_seq_puts() Tzvetomir Stoyanov
@ 2019-03-08 13:36 ` Tzvetomir Stoyanov
2019-03-08 14:19 ` [PATCH v4 00/46] Libtraceevent MAN pages Claudio
46 siblings, 0 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 13:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
Create man pages for trace_seq_reset() and trace_seq_terminate()
as part of the libtraceevent APIs.
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-tseq_reset.txt | 78 +++++++++++++++++++
1 file changed, 78 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
new file mode 100644
index 000000000000..a70c0b2f152f
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+trace_seq_reset,trace_seq_terminate - Reset / terminate a trace sequence.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+*#include <trace-seq.h>*
+
+void *trace_seq_reset*(struct trace_seq pass:[*]_s_);
+void *trace_seq_terminate*(struct trace_seq pass:[*]_s_);
+--
+
+DESCRIPTION
+-----------
+Trace sequences are used to allow a function to call several other functions
+to create a string of data to use.
+
+The _trace_seq_reset()_ function re-initializes the trace sequence _s_. All
+characters already written in _s_ will be deleted.
+
+The _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts
+the null character pass:['\0'] at the end of the buffer.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+#include <trace-seq.h>
+...
+struct trace_seq seq;
+trace_seq_init(&seq);
+...
+trace_seq_reset(&seq);
+...
+trace_seq_terminate(&seq);
+...
+--
+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.
+*-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
--
2.20.1
^ permalink raw reply related [flat|nested] 80+ messages in thread* Re: [PATCH v4 00/46] Libtraceevent MAN pages
2019-03-08 13:36 [PATCH v4 00/46] Libtraceevent MAN pages Tzvetomir Stoyanov
` (45 preceding siblings ...)
2019-03-08 13:36 ` [PATCH v4 46/46] tools/lib/traceevent: Man pages for trace_seq_reset() and trace_seq_terminate() Tzvetomir Stoyanov
@ 2019-03-08 14:19 ` Claudio
2019-03-08 15:47 ` Tzvetomir Stoyanov
46 siblings, 1 reply; 80+ messages in thread
From: Claudio @ 2019-03-08 14:19 UTC (permalink / raw)
To: Tzvetomir Stoyanov, rostedt; +Cc: linux-trace-devel
On 3/8/19 2:36 PM, Tzvetomir Stoyanov wrote:
> [
> V4 changes:
> - Addressed Steven Rostedt comments
> - Removed trailing whitespace
>
> V3 changes:
> - Combines all man page related patches into one series.
> - Removes any dependencies between man page related patches
> and patches related to the APIs implementation.
> ]
>
> This patch series includes implementation of libtraceevent
> man pages, describing all APIs of the library.
Hello,
is there a general man page entry that explains what libtracevent does?
Maybe a manual section 3 or 7 entry like
LIBTRACEEVENT(3)
Maybe I have missed it? I think it would helpful, to avoid a disconnect between what a user might expect the library to do,
vs what it actually does, to which use case it is suited for.
Just as a case in point, at the moment these are the features which would be needed for me to use this
library for the real time tracing requirements I am facing (response times, fixed allocation of cpu tracing usage/overhead):
- resource usage description of APIs, which APIs allocate memory, open file descriptors and such,
some examples of resource lifetime would be helpful (pardon if they are there already and I missed them)
- support for in-order delivery of events already correlated from multiple cores
- network streaming support (maybe already working?)
- support for getting TGID in addition to the COMM for each (sched) event in addition to the PID.
Currently we have implemented all of this inside the application,
but we could get rid of this complexity in the future if this library could provide this out of the box,
without serious impacts on cpu overhead and latency requirements.
Just a simple description of the overall goals of the library and common patterns,
notes on resource usage, etc, would be enough I think to be able to quickly see if it fits the application use case..
Thank you,
Claudio
>
> Tzvetomir Stoyanov (46):
> tools/lib/traceevent: Implement libtraceevent man pages
> tools/lib/traceevent: Fix libtraceevent/Documentation Makefile
> tools/lib/traceevent: Add support for man pages with multiple names
> tools/lib/traceevent: libtraceevent Makefile "help" target
> tools/lib/traceevent: libtraceevent man pages for tep_handler related
> APIs
> tools/lib/traceevent: Man page for tep_get_header_page_size()
> tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus()
> tools/lib/traceevent: Man page for tep_is_file_bigendian() and
> tep_set_file_bigendian()
> tools/lib/traceevent: Man page for tep_is_host_bigendian() and
> tep_set_host_bigendian()
> tools/lib/traceevent: Man page for tep_is_latency_format() and
> tep_set_latency_format()
> tools/lib/traceevent: Man page for tep_get_page_size() and
> tep_set_page_size()
> tools/lib/traceevent: Man page for tep_strerror()
> tools/lib/traceevent: Man page for tep_register_trace_clock()
> tools/lib/traceevent: Man pages for tep_register_event_handler() and
> tep_unregister_event_handler()
> tools/lib/traceevent: Man pages for tep_register_function() and
> tep_register_print_string()
> tools/lib/traceevent: Man pages for tep_register_print_function() and
> tep_unregister_print_function()
> tools/lib/traceevent: Man page for tep_read_number()
> tools/lib/traceevent: Man pages for tep_find_event(),
> tep_find_event_by_name() and tep_find_event_by_record()
> tools/lib/traceevent: Man page for tep_list_events()
> tools/lib/traceevent: Man pages for tep_print_event(),
> tep_print_event_data(), tep_event_info(), tep_print_event_task() and
> tep_print_event_time()
> tools/lib/traceevent: Man pages tep_get_first_event() and
> tep_get_events_count()
> tools/lib/traceevent: Man pages tep_find_common_field(),
> tep_find_field() and tep_find_any_field()
> tools/lib/traceevent: Man pages tep_get_any_field_val(),
> tep_get_common_field_val(), tep_get_field_val() and
> tep_get_field_raw()
> tools/lib/traceevent: Man pages for tep_print_field(),
> tep_print_fields(), tep_print_num_field() and tep_print_func_field()
> tools/lib/traceevent: Man page for tep_read_number_field()
> tools/lib/traceevent: Man pages for tep_event_common_fields() and
> tep_event_fields()
> tools/lib/traceevent: Man pages for tep_filter_alloc(),
> tep_filter_free() and tep_filter_reset()
> tools/lib/traceevent: Man page for tep_filter_add_filter_str()
> tools/lib/traceevent: Man page for tep_filter_strerror()
> tools/lib/traceevent: Man pages for tep_event_filtered() and
> tep_filter_remove_event()
> tools/lib/traceevent: Man page for tep_filter_match()
> tools/lib/traceevent: Man pages for tep_filter_copy() and
> tep_filter_compare()
> tools/lib/traceevent: Man page for tep_filter_make_string()
> tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(),
> tep_update_trivial() and tep_filter_clear_trivial()
> tools/lib/traceevent: Man pages for tep_find_function() and
> tep_find_function_address()
> tools/lib/traceevent: Man pages for tep_set_function_resolver() and
> tep_reset_function_resolver()
> tools/lib/traceevent: Man pages for tep_parse_event() and
> tep_parse_format()
> tools/lib/traceevent: Man page for tep_parse_header_page()
> tools/lib/traceevent: Man pages for tep_load_plugins() and
> tep_unload_plugin()
> tools/lib/traceevent: Man page for tep_data_lat_fmt()
> tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(),
> tep_data_preempt_count() and tep_data_flags()
> tools/lib/traceevent: Man pages for trace_seq_init() and
> trace_seq_destroy()
> tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and
> trace_seq_do_printf()
> tools/lib/traceevent: Man pages for trace_seq_printf() and
> trace_seq_vprintf()
> tools/lib/traceevent: Man pages for trace_seq_putc() and
> trace_seq_puts()
> tools/lib/traceevent: Man pages for trace_seq_reset() and
> trace_seq_terminate()
>
> tools/lib/traceevent/Documentation/Makefile | 208 ++++++++++++++++++
> .../traceevent/Documentation/asciidoc.conf | 120 ++++++++++
> .../Documentation/libtraceevent-commands.txt | 130 +++++++++++
> .../Documentation/libtraceevent-cpus.txt | 77 +++++++
> .../libtraceevent-endian_read.txt | 76 +++++++
> .../libtraceevent-event_find.txt | 99 +++++++++
> .../libtraceevent-event_list.txt | 94 ++++++++
> .../libtraceevent-event_print.txt | 126 +++++++++++
> .../Documentation/libtraceevent-events.txt | 87 ++++++++
> .../libtraceevent-field_find.txt | 98 +++++++++
> .../libtraceevent-field_get_val.txt | 117 ++++++++++
> .../libtraceevent-field_print.txt | 120 ++++++++++
> .../libtraceevent-field_read.txt | 80 +++++++
> .../Documentation/libtraceevent-fields.txt | 99 +++++++++
> .../libtraceevent-file_endian.txt | 89 ++++++++
> .../Documentation/libtraceevent-filter.txt | 85 +++++++
> .../libtraceevent-filter_add.txt | 78 +++++++
> .../libtraceevent-filter_error.txt | 78 +++++++
> .../libtraceevent-filter_event.txt | 84 +++++++
> .../libtraceevent-filter_match.txt | 96 ++++++++
> .../libtraceevent-filter_oper.txt | 84 +++++++
> .../libtraceevent-filter_show.txt | 75 +++++++
> .../libtraceevent-filter_trivial.txt | 112 ++++++++++
> .../Documentation/libtraceevent-func_find.txt | 88 ++++++++
> .../libtraceevent-func_resolve.txt | 96 ++++++++
> .../Documentation/libtraceevent-handle.txt | 101 +++++++++
> .../libtraceevent-header_size.txt | 73 ++++++
> .../libtraceevent-host_endian.txt | 91 ++++++++
> .../libtraceevent-latency_format.txt | 140 ++++++++++++
> .../Documentation/libtraceevent-long_size.txt | 78 +++++++
> .../Documentation/libtraceevent-page_size.txt | 80 +++++++
> .../libtraceevent-parse_event.txt | 90 ++++++++
> .../libtraceevent-parse_head.txt | 82 +++++++
> .../Documentation/libtraceevent-plugins.txt | 98 +++++++++
> .../libtraceevent-record_lat.txt | 77 +++++++
> .../libtraceevent-record_parse.txt | 134 +++++++++++
> .../Documentation/libtraceevent-reg_clock.txt | 77 +++++++
> .../libtraceevent-reg_event_handler.txt | 129 +++++++++++
> .../libtraceevent-reg_funcstr.txt | 89 ++++++++
> .../libtraceevent-reg_print_func.txt | 128 +++++++++++
> .../Documentation/libtraceevent-set_flag.txt | 90 ++++++++
> .../Documentation/libtraceevent-strerror.txt | 78 +++++++
> .../Documentation/libtraceevent-tseq.txt | 76 +++++++
> .../libtraceevent-tseq_doprint.txt | 89 ++++++++
> .../libtraceevent-tseq_print.txt | 96 ++++++++
> .../Documentation/libtraceevent-tseq_put.txt | 89 ++++++++
> .../libtraceevent-tseq_reset.txt | 78 +++++++
> .../Documentation/libtraceevent.txt | 198 +++++++++++++++++
> .../traceevent/Documentation/manpage-1.72.xsl | 14 ++
> .../traceevent/Documentation/manpage-base.xsl | 35 +++
> .../Documentation/manpage-bold-literal.xsl | 17 ++
> .../Documentation/manpage-normal.xsl | 13 ++
> .../Documentation/manpage-suppress-sp.xsl | 21 ++
> tools/lib/traceevent/Makefile | 28 +++
> 54 files changed, 4885 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/Makefile
> create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
> create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
> create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
>
^ permalink raw reply [flat|nested] 80+ messages in thread* Re: [PATCH v4 00/46] Libtraceevent MAN pages
2019-03-08 14:19 ` [PATCH v4 00/46] Libtraceevent MAN pages Claudio
@ 2019-03-08 15:47 ` Tzvetomir Stoyanov
2019-03-08 18:52 ` Claudio
2019-03-12 15:35 ` Steven Rostedt
0 siblings, 2 replies; 80+ messages in thread
From: Tzvetomir Stoyanov @ 2019-03-08 15:47 UTC (permalink / raw)
To: Claudio; +Cc: Steven Rostedt, linux-trace-devel
Hi Claudio,
On Fri, Mar 8, 2019 at 4:19 PM Claudio <claudio.fontana@gliwa.com> wrote:
>
>
>
> On 3/8/19 2:36 PM, Tzvetomir Stoyanov wrote:
> > [
> > V4 changes:
> > - Addressed Steven Rostedt comments
> > - Removed trailing whitespace
> >
> > V3 changes:
> > - Combines all man page related patches into one series.
> > - Removes any dependencies between man page related patches
> > and patches related to the APIs implementation.
> > ]
> >
> > This patch series includes implementation of libtraceevent
> > man pages, describing all APIs of the library.
>
> Hello,
>
> is there a general man page entry that explains what libtracevent does?
>
> Maybe a manual section 3 or 7 entry like
>
> LIBTRACEEVENT(3)
>
> Maybe I have missed it? I think it would helpful, to avoid a disconnect between what a user might expect the library to do,
> vs what it actually does, to which use case it is suited for.
>
There is libtraceevent(3) man page, part of the first patch from the
series - "tools/lib/traceevent: Implement libtraceevent man pages ",
file tools/lib/traceevent/Documentation/libtraceevent.txt. It contains
summary of all APIs and short description of the library.
> Just as a case in point, at the moment these are the features which would be needed for me to use this
> library for the real time tracing requirements I am facing (response times, fixed allocation of cpu tracing usage/overhead):
>
> - resource usage description of APIs, which APIs allocate memory, open file descriptors and such,
> some examples of resource lifetime would be helpful (pardon if they are there already and I missed them)
There are such description in the relevant man pages, together with
examples - look at tep_alloc man page for example. Any feedback is
welcome.
>
> - support for in-order delivery of events already correlated from multiple cores
>
> - network streaming support (maybe already working?)
>
> - support for getting TGID in addition to the COMM for each (sched) event in addition to the PID.
>
> Currently we have implemented all of this inside the application,
> but we could get rid of this complexity in the future if this library could provide this out of the box,
> without serious impacts on cpu overhead and latency requirements.
>
> Just a simple description of the overall goals of the library and common patterns,
> notes on resource usage, etc, would be enough I think to be able to quickly see if it fits the application use case..
>
> Thank you,
>
> Claudio
>
Steven could describe it in more details, but we work on common
tracing platform - set of libraries, which will expose the tracing
functionality, currently available for trace-cmd and kernelshark only,
to any application.
> >
> > Tzvetomir Stoyanov (46):
> > tools/lib/traceevent: Implement libtraceevent man pages
> > tools/lib/traceevent: Fix libtraceevent/Documentation Makefile
> > tools/lib/traceevent: Add support for man pages with multiple names
> > tools/lib/traceevent: libtraceevent Makefile "help" target
> > tools/lib/traceevent: libtraceevent man pages for tep_handler related
> > APIs
> > tools/lib/traceevent: Man page for tep_get_header_page_size()
> > tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus()
> > tools/lib/traceevent: Man page for tep_is_file_bigendian() and
> > tep_set_file_bigendian()
> > tools/lib/traceevent: Man page for tep_is_host_bigendian() and
> > tep_set_host_bigendian()
> > tools/lib/traceevent: Man page for tep_is_latency_format() and
> > tep_set_latency_format()
> > tools/lib/traceevent: Man page for tep_get_page_size() and
> > tep_set_page_size()
> > tools/lib/traceevent: Man page for tep_strerror()
> > tools/lib/traceevent: Man page for tep_register_trace_clock()
> > tools/lib/traceevent: Man pages for tep_register_event_handler() and
> > tep_unregister_event_handler()
> > tools/lib/traceevent: Man pages for tep_register_function() and
> > tep_register_print_string()
> > tools/lib/traceevent: Man pages for tep_register_print_function() and
> > tep_unregister_print_function()
> > tools/lib/traceevent: Man page for tep_read_number()
> > tools/lib/traceevent: Man pages for tep_find_event(),
> > tep_find_event_by_name() and tep_find_event_by_record()
> > tools/lib/traceevent: Man page for tep_list_events()
> > tools/lib/traceevent: Man pages for tep_print_event(),
> > tep_print_event_data(), tep_event_info(), tep_print_event_task() and
> > tep_print_event_time()
> > tools/lib/traceevent: Man pages tep_get_first_event() and
> > tep_get_events_count()
> > tools/lib/traceevent: Man pages tep_find_common_field(),
> > tep_find_field() and tep_find_any_field()
> > tools/lib/traceevent: Man pages tep_get_any_field_val(),
> > tep_get_common_field_val(), tep_get_field_val() and
> > tep_get_field_raw()
> > tools/lib/traceevent: Man pages for tep_print_field(),
> > tep_print_fields(), tep_print_num_field() and tep_print_func_field()
> > tools/lib/traceevent: Man page for tep_read_number_field()
> > tools/lib/traceevent: Man pages for tep_event_common_fields() and
> > tep_event_fields()
> > tools/lib/traceevent: Man pages for tep_filter_alloc(),
> > tep_filter_free() and tep_filter_reset()
> > tools/lib/traceevent: Man page for tep_filter_add_filter_str()
> > tools/lib/traceevent: Man page for tep_filter_strerror()
> > tools/lib/traceevent: Man pages for tep_event_filtered() and
> > tep_filter_remove_event()
> > tools/lib/traceevent: Man page for tep_filter_match()
> > tools/lib/traceevent: Man pages for tep_filter_copy() and
> > tep_filter_compare()
> > tools/lib/traceevent: Man page for tep_filter_make_string()
> > tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(),
> > tep_update_trivial() and tep_filter_clear_trivial()
> > tools/lib/traceevent: Man pages for tep_find_function() and
> > tep_find_function_address()
> > tools/lib/traceevent: Man pages for tep_set_function_resolver() and
> > tep_reset_function_resolver()
> > tools/lib/traceevent: Man pages for tep_parse_event() and
> > tep_parse_format()
> > tools/lib/traceevent: Man page for tep_parse_header_page()
> > tools/lib/traceevent: Man pages for tep_load_plugins() and
> > tep_unload_plugin()
> > tools/lib/traceevent: Man page for tep_data_lat_fmt()
> > tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(),
> > tep_data_preempt_count() and tep_data_flags()
> > tools/lib/traceevent: Man pages for trace_seq_init() and
> > trace_seq_destroy()
> > tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and
> > trace_seq_do_printf()
> > tools/lib/traceevent: Man pages for trace_seq_printf() and
> > trace_seq_vprintf()
> > tools/lib/traceevent: Man pages for trace_seq_putc() and
> > trace_seq_puts()
> > tools/lib/traceevent: Man pages for trace_seq_reset() and
> > trace_seq_terminate()
> >
> > tools/lib/traceevent/Documentation/Makefile | 208 ++++++++++++++++++
> > .../traceevent/Documentation/asciidoc.conf | 120 ++++++++++
> > .../Documentation/libtraceevent-commands.txt | 130 +++++++++++
> > .../Documentation/libtraceevent-cpus.txt | 77 +++++++
> > .../libtraceevent-endian_read.txt | 76 +++++++
> > .../libtraceevent-event_find.txt | 99 +++++++++
> > .../libtraceevent-event_list.txt | 94 ++++++++
> > .../libtraceevent-event_print.txt | 126 +++++++++++
> > .../Documentation/libtraceevent-events.txt | 87 ++++++++
> > .../libtraceevent-field_find.txt | 98 +++++++++
> > .../libtraceevent-field_get_val.txt | 117 ++++++++++
> > .../libtraceevent-field_print.txt | 120 ++++++++++
> > .../libtraceevent-field_read.txt | 80 +++++++
> > .../Documentation/libtraceevent-fields.txt | 99 +++++++++
> > .../libtraceevent-file_endian.txt | 89 ++++++++
> > .../Documentation/libtraceevent-filter.txt | 85 +++++++
> > .../libtraceevent-filter_add.txt | 78 +++++++
> > .../libtraceevent-filter_error.txt | 78 +++++++
> > .../libtraceevent-filter_event.txt | 84 +++++++
> > .../libtraceevent-filter_match.txt | 96 ++++++++
> > .../libtraceevent-filter_oper.txt | 84 +++++++
> > .../libtraceevent-filter_show.txt | 75 +++++++
> > .../libtraceevent-filter_trivial.txt | 112 ++++++++++
> > .../Documentation/libtraceevent-func_find.txt | 88 ++++++++
> > .../libtraceevent-func_resolve.txt | 96 ++++++++
> > .../Documentation/libtraceevent-handle.txt | 101 +++++++++
> > .../libtraceevent-header_size.txt | 73 ++++++
> > .../libtraceevent-host_endian.txt | 91 ++++++++
> > .../libtraceevent-latency_format.txt | 140 ++++++++++++
> > .../Documentation/libtraceevent-long_size.txt | 78 +++++++
> > .../Documentation/libtraceevent-page_size.txt | 80 +++++++
> > .../libtraceevent-parse_event.txt | 90 ++++++++
> > .../libtraceevent-parse_head.txt | 82 +++++++
> > .../Documentation/libtraceevent-plugins.txt | 98 +++++++++
> > .../libtraceevent-record_lat.txt | 77 +++++++
> > .../libtraceevent-record_parse.txt | 134 +++++++++++
> > .../Documentation/libtraceevent-reg_clock.txt | 77 +++++++
> > .../libtraceevent-reg_event_handler.txt | 129 +++++++++++
> > .../libtraceevent-reg_funcstr.txt | 89 ++++++++
> > .../libtraceevent-reg_print_func.txt | 128 +++++++++++
> > .../Documentation/libtraceevent-set_flag.txt | 90 ++++++++
> > .../Documentation/libtraceevent-strerror.txt | 78 +++++++
> > .../Documentation/libtraceevent-tseq.txt | 76 +++++++
> > .../libtraceevent-tseq_doprint.txt | 89 ++++++++
> > .../libtraceevent-tseq_print.txt | 96 ++++++++
> > .../Documentation/libtraceevent-tseq_put.txt | 89 ++++++++
> > .../libtraceevent-tseq_reset.txt | 78 +++++++
> > .../Documentation/libtraceevent.txt | 198 +++++++++++++++++
> > .../traceevent/Documentation/manpage-1.72.xsl | 14 ++
> > .../traceevent/Documentation/manpage-base.xsl | 35 +++
> > .../Documentation/manpage-bold-literal.xsl | 17 ++
> > .../Documentation/manpage-normal.xsl | 13 ++
> > .../Documentation/manpage-suppress-sp.xsl | 21 ++
> > tools/lib/traceevent/Makefile | 28 +++
> > 54 files changed, 4885 insertions(+)
> > create mode 100644 tools/lib/traceevent/Documentation/Makefile
> > create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
> > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
> > create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
> >
>
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 00/46] Libtraceevent MAN pages
2019-03-08 15:47 ` Tzvetomir Stoyanov
@ 2019-03-08 18:52 ` Claudio
2019-03-12 15:35 ` Steven Rostedt
1 sibling, 0 replies; 80+ messages in thread
From: Claudio @ 2019-03-08 18:52 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: Steven Rostedt, linux-trace-devel
Hello Tzvetomir,
On 3/8/19 4:47 PM, Tzvetomir Stoyanov wrote:
> Hi Claudio,
> On Fri, Mar 8, 2019 at 4:19 PM Claudio <claudio.fontana@gliwa.com> wrote:
>>
>>
>>
>> On 3/8/19 2:36 PM, Tzvetomir Stoyanov wrote:
>>> [
>>> V4 changes:
>>> - Addressed Steven Rostedt comments
>>> - Removed trailing whitespace
>>>
>>> V3 changes:
>>> - Combines all man page related patches into one series.
>>> - Removes any dependencies between man page related patches
>>> and patches related to the APIs implementation.
>>> ]
>>>
>>> This patch series includes implementation of libtraceevent
>>> man pages, describing all APIs of the library.
>>
>> Hello,
>>
>> is there a general man page entry that explains what libtracevent does?
>>
>> Maybe a manual section 3 or 7 entry like
>>
>> LIBTRACEEVENT(3)
>>
>> Maybe I have missed it? I think it would helpful, to avoid a disconnect between what a user might expect the library to do,
>> vs what it actually does, to which use case it is suited for.
>>
>
> There is libtraceevent(3) man page, part of the first patch from the
> series - "tools/lib/traceevent: Implement libtraceevent man pages ",
> file tools/lib/traceevent/Documentation/libtraceevent.txt. It contains
> summary of all APIs and short description of the library.
Thank you very much, I completely missed it before, it was right there :-)
Ciao,
Claudio
>> Just as a case in point, at the moment these are the features which would be needed for me to use this
>> library for the real time tracing requirements I am facing (response times, fixed allocation of cpu tracing usage/overhead):
>>
>> - resource usage description of APIs, which APIs allocate memory, open file descriptors and such,
>> some examples of resource lifetime would be helpful (pardon if they are there already and I missed them)
>
> There are such description in the relevant man pages, together with
> examples - look at tep_alloc man page for example. Any feedback is
> welcome.
>
>>
>> - support for in-order delivery of events already correlated from multiple cores
>>
>> - network streaming support (maybe already working?)
>>
>> - support for getting TGID in addition to the COMM for each (sched) event in addition to the PID.
>>
>> Currently we have implemented all of this inside the application,
>> but we could get rid of this complexity in the future if this library could provide this out of the box,
>> without serious impacts on cpu overhead and latency requirements.
>>
>> Just a simple description of the overall goals of the library and common patterns,
>> notes on resource usage, etc, would be enough I think to be able to quickly see if it fits the application use case..
>>
>> Thank you,
>>
>> Claudio
>>
>
> Steven could describe it in more details, but we work on common
> tracing platform - set of libraries, which will expose the tracing
> functionality, currently available for trace-cmd and kernelshark only,
> to any application.
>
>>>
>>> Tzvetomir Stoyanov (46):
>>> tools/lib/traceevent: Implement libtraceevent man pages
>>> tools/lib/traceevent: Fix libtraceevent/Documentation Makefile
>>> tools/lib/traceevent: Add support for man pages with multiple names
>>> tools/lib/traceevent: libtraceevent Makefile "help" target
>>> tools/lib/traceevent: libtraceevent man pages for tep_handler related
>>> APIs
>>> tools/lib/traceevent: Man page for tep_get_header_page_size()
>>> tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus()
>>> tools/lib/traceevent: Man page for tep_is_file_bigendian() and
>>> tep_set_file_bigendian()
>>> tools/lib/traceevent: Man page for tep_is_host_bigendian() and
>>> tep_set_host_bigendian()
>>> tools/lib/traceevent: Man page for tep_is_latency_format() and
>>> tep_set_latency_format()
>>> tools/lib/traceevent: Man page for tep_get_page_size() and
>>> tep_set_page_size()
>>> tools/lib/traceevent: Man page for tep_strerror()
>>> tools/lib/traceevent: Man page for tep_register_trace_clock()
>>> tools/lib/traceevent: Man pages for tep_register_event_handler() and
>>> tep_unregister_event_handler()
>>> tools/lib/traceevent: Man pages for tep_register_function() and
>>> tep_register_print_string()
>>> tools/lib/traceevent: Man pages for tep_register_print_function() and
>>> tep_unregister_print_function()
>>> tools/lib/traceevent: Man page for tep_read_number()
>>> tools/lib/traceevent: Man pages for tep_find_event(),
>>> tep_find_event_by_name() and tep_find_event_by_record()
>>> tools/lib/traceevent: Man page for tep_list_events()
>>> tools/lib/traceevent: Man pages for tep_print_event(),
>>> tep_print_event_data(), tep_event_info(), tep_print_event_task() and
>>> tep_print_event_time()
>>> tools/lib/traceevent: Man pages tep_get_first_event() and
>>> tep_get_events_count()
>>> tools/lib/traceevent: Man pages tep_find_common_field(),
>>> tep_find_field() and tep_find_any_field()
>>> tools/lib/traceevent: Man pages tep_get_any_field_val(),
>>> tep_get_common_field_val(), tep_get_field_val() and
>>> tep_get_field_raw()
>>> tools/lib/traceevent: Man pages for tep_print_field(),
>>> tep_print_fields(), tep_print_num_field() and tep_print_func_field()
>>> tools/lib/traceevent: Man page for tep_read_number_field()
>>> tools/lib/traceevent: Man pages for tep_event_common_fields() and
>>> tep_event_fields()
>>> tools/lib/traceevent: Man pages for tep_filter_alloc(),
>>> tep_filter_free() and tep_filter_reset()
>>> tools/lib/traceevent: Man page for tep_filter_add_filter_str()
>>> tools/lib/traceevent: Man page for tep_filter_strerror()
>>> tools/lib/traceevent: Man pages for tep_event_filtered() and
>>> tep_filter_remove_event()
>>> tools/lib/traceevent: Man page for tep_filter_match()
>>> tools/lib/traceevent: Man pages for tep_filter_copy() and
>>> tep_filter_compare()
>>> tools/lib/traceevent: Man page for tep_filter_make_string()
>>> tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(),
>>> tep_update_trivial() and tep_filter_clear_trivial()
>>> tools/lib/traceevent: Man pages for tep_find_function() and
>>> tep_find_function_address()
>>> tools/lib/traceevent: Man pages for tep_set_function_resolver() and
>>> tep_reset_function_resolver()
>>> tools/lib/traceevent: Man pages for tep_parse_event() and
>>> tep_parse_format()
>>> tools/lib/traceevent: Man page for tep_parse_header_page()
>>> tools/lib/traceevent: Man pages for tep_load_plugins() and
>>> tep_unload_plugin()
>>> tools/lib/traceevent: Man page for tep_data_lat_fmt()
>>> tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(),
>>> tep_data_preempt_count() and tep_data_flags()
>>> tools/lib/traceevent: Man pages for trace_seq_init() and
>>> trace_seq_destroy()
>>> tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and
>>> trace_seq_do_printf()
>>> tools/lib/traceevent: Man pages for trace_seq_printf() and
>>> trace_seq_vprintf()
>>> tools/lib/traceevent: Man pages for trace_seq_putc() and
>>> trace_seq_puts()
>>> tools/lib/traceevent: Man pages for trace_seq_reset() and
>>> trace_seq_terminate()
>>>
>>> tools/lib/traceevent/Documentation/Makefile | 208 ++++++++++++++++++
>>> .../traceevent/Documentation/asciidoc.conf | 120 ++++++++++
>>> .../Documentation/libtraceevent-commands.txt | 130 +++++++++++
>>> .../Documentation/libtraceevent-cpus.txt | 77 +++++++
>>> .../libtraceevent-endian_read.txt | 76 +++++++
>>> .../libtraceevent-event_find.txt | 99 +++++++++
>>> .../libtraceevent-event_list.txt | 94 ++++++++
>>> .../libtraceevent-event_print.txt | 126 +++++++++++
>>> .../Documentation/libtraceevent-events.txt | 87 ++++++++
>>> .../libtraceevent-field_find.txt | 98 +++++++++
>>> .../libtraceevent-field_get_val.txt | 117 ++++++++++
>>> .../libtraceevent-field_print.txt | 120 ++++++++++
>>> .../libtraceevent-field_read.txt | 80 +++++++
>>> .../Documentation/libtraceevent-fields.txt | 99 +++++++++
>>> .../libtraceevent-file_endian.txt | 89 ++++++++
>>> .../Documentation/libtraceevent-filter.txt | 85 +++++++
>>> .../libtraceevent-filter_add.txt | 78 +++++++
>>> .../libtraceevent-filter_error.txt | 78 +++++++
>>> .../libtraceevent-filter_event.txt | 84 +++++++
>>> .../libtraceevent-filter_match.txt | 96 ++++++++
>>> .../libtraceevent-filter_oper.txt | 84 +++++++
>>> .../libtraceevent-filter_show.txt | 75 +++++++
>>> .../libtraceevent-filter_trivial.txt | 112 ++++++++++
>>> .../Documentation/libtraceevent-func_find.txt | 88 ++++++++
>>> .../libtraceevent-func_resolve.txt | 96 ++++++++
>>> .../Documentation/libtraceevent-handle.txt | 101 +++++++++
>>> .../libtraceevent-header_size.txt | 73 ++++++
>>> .../libtraceevent-host_endian.txt | 91 ++++++++
>>> .../libtraceevent-latency_format.txt | 140 ++++++++++++
>>> .../Documentation/libtraceevent-long_size.txt | 78 +++++++
>>> .../Documentation/libtraceevent-page_size.txt | 80 +++++++
>>> .../libtraceevent-parse_event.txt | 90 ++++++++
>>> .../libtraceevent-parse_head.txt | 82 +++++++
>>> .../Documentation/libtraceevent-plugins.txt | 98 +++++++++
>>> .../libtraceevent-record_lat.txt | 77 +++++++
>>> .../libtraceevent-record_parse.txt | 134 +++++++++++
>>> .../Documentation/libtraceevent-reg_clock.txt | 77 +++++++
>>> .../libtraceevent-reg_event_handler.txt | 129 +++++++++++
>>> .../libtraceevent-reg_funcstr.txt | 89 ++++++++
>>> .../libtraceevent-reg_print_func.txt | 128 +++++++++++
>>> .../Documentation/libtraceevent-set_flag.txt | 90 ++++++++
>>> .../Documentation/libtraceevent-strerror.txt | 78 +++++++
>>> .../Documentation/libtraceevent-tseq.txt | 76 +++++++
>>> .../libtraceevent-tseq_doprint.txt | 89 ++++++++
>>> .../libtraceevent-tseq_print.txt | 96 ++++++++
>>> .../Documentation/libtraceevent-tseq_put.txt | 89 ++++++++
>>> .../libtraceevent-tseq_reset.txt | 78 +++++++
>>> .../Documentation/libtraceevent.txt | 198 +++++++++++++++++
>>> .../traceevent/Documentation/manpage-1.72.xsl | 14 ++
>>> .../traceevent/Documentation/manpage-base.xsl | 35 +++
>>> .../Documentation/manpage-bold-literal.xsl | 17 ++
>>> .../Documentation/manpage-normal.xsl | 13 ++
>>> .../Documentation/manpage-suppress-sp.xsl | 21 ++
>>> tools/lib/traceevent/Makefile | 28 +++
>>> 54 files changed, 4885 insertions(+)
>>> create mode 100644 tools/lib/traceevent/Documentation/Makefile
>>> create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt
>>> create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl
>>> create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl
>>> create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl
>>> create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl
>>> create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
>>>
>>
>
>
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 00/46] Libtraceevent MAN pages
2019-03-08 15:47 ` Tzvetomir Stoyanov
2019-03-08 18:52 ` Claudio
@ 2019-03-12 15:35 ` Steven Rostedt
2019-03-13 11:24 ` Claudio
1 sibling, 1 reply; 80+ messages in thread
From: Steven Rostedt @ 2019-03-12 15:35 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: Claudio, linux-trace-devel
On Fri, 8 Mar 2019 15:47:14 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
> Steven could describe it in more details, but we work on common
> tracing platform - set of libraries, which will expose the tracing
> functionality, currently available for trace-cmd and kernelshark only,
> to any application.
[ Just came back from SCaLE 17x conference ]
Note, the libtraceevent is currently just a way to parse the data read
by the Linux kernel trace events. The format files exist in the tracefs
file system under events/<system>/<event>/format (e.g.
events/sched/sched_switch/format).
The library is used by trace-cmd, perf, powertop and mce utils.
Currently, each has their own copy. We are working on making this into
a shared library where the code no longer needs to be duplicated.
There's also going to be an effort to create libftrace, that will take
the functionality of trace-cmd and move it into a library, such that
any tool can start ftrace tracing, and record data. But that's not going
to happen until after we finish getting libtraceevent out.
-- Steve
^ permalink raw reply [flat|nested] 80+ messages in thread
* Re: [PATCH v4 00/46] Libtraceevent MAN pages
2019-03-12 15:35 ` Steven Rostedt
@ 2019-03-13 11:24 ` Claudio
0 siblings, 0 replies; 80+ messages in thread
From: Claudio @ 2019-03-13 11:24 UTC (permalink / raw)
To: Steven Rostedt, Tzvetomir Stoyanov; +Cc: linux-trace-devel
Hi Steve,
On 3/12/19 4:35 PM, Steven Rostedt wrote:
> On Fri, 8 Mar 2019 15:47:14 +0000
> Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
>> Steven could describe it in more details, but we work on common
>> tracing platform - set of libraries, which will expose the tracing
>> functionality, currently available for trace-cmd and kernelshark only,
>> to any application.
>
> [ Just came back from SCaLE 17x conference ]
>
> Note, the libtraceevent is currently just a way to parse the data read
> by the Linux kernel trace events. The format files exist in the tracefs
> file system under events/<system>/<event>/format (e.g.
> events/sched/sched_switch/format).
>
> The library is used by trace-cmd, perf, powertop and mce utils.
> Currently, each has their own copy. We are working on making this into
> a shared library where the code no longer needs to be duplicated.
> There's also going to be an effort to create libftrace, that will take
> the functionality of trace-cmd and move it into a library, such that
> any tool can start ftrace tracing, and record data. But that's not going
> to happen until after we finish getting libtraceevent out.
>
> -- Steve
>
thank you for this background information, this solves my confusion at the moment.
I currently have my own code that parses the data, based on the event/format,
so I will not replace it immediately, I think that the really valuable replacement
would be the libftrace follow up project.
Ciao,
CLaudio
^ permalink raw reply [flat|nested] 80+ messages in thread