linux-trace-devel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v2 0/8] libtracefs man pages
@ 2020-12-21  6:02 Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 1/8] libtracefs: Initial support for " Tzvetomir Stoyanov (VMware)
                   ` (7 more replies)
  0 siblings, 8 replies; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Initial implementation of libtracefs man pages.

v2 changes:
 - Removed tracefs_find_tracing_dir() API
 - Renamed tracefs_get_tracing_dir() to tracefs_tracing_dir()
 - Removed any references to "#include <event-parse.h>"
 - Rewrote some descriptions, as suggested by Steven.

Tzvetomir Stoyanov (VMware) (8):
  libtracefs: Initial support for man pages
  libtracefs man pages: APIs for locating trace directory and files.
  libtracefs man pages: APIs for working with trace systems and events.
  libtracefs man pages: APIs for managing trace instances.
  libtracefs man pages: APIs for working with files in trace instances.
  libtracefs man pages: helper APIs for working with trace instances.
  libtracefs man pages: APIs for initializing a tep handler with trace
    events from the local system.
  libtracefs man pages: helper APIs for working with trace file system.

 Documentation/Makefile                        | 211 ++++++++++++++++++
 Documentation/asciidoc.conf                   | 120 ++++++++++
 Documentation/libtracefs-events-tep.txt       | 131 +++++++++++
 Documentation/libtracefs-events.txt           | 143 ++++++++++++
 Documentation/libtracefs-files.txt            |  97 ++++++++
 Documentation/libtracefs-instances-files.txt  | 160 +++++++++++++
 Documentation/libtracefs-instances-manage.txt | 111 +++++++++
 Documentation/libtracefs-instances-utils.txt  | 112 ++++++++++
 Documentation/libtracefs-utils.txt            | 103 +++++++++
 Documentation/libtracefs.txt                  |  84 +++++++
 Documentation/manpage-1.72.xsl                |  14 ++
 Documentation/manpage-base.xsl                |  35 +++
 Documentation/manpage-bold-literal.xsl        |  17 ++
 Documentation/manpage-normal.xsl              |  13 ++
 Documentation/manpage-suppress-sp.xsl         |  21 ++
 15 files changed, 1372 insertions(+)
 create mode 100644 Documentation/Makefile
 create mode 100644 Documentation/asciidoc.conf
 create mode 100644 Documentation/libtracefs-events-tep.txt
 create mode 100644 Documentation/libtracefs-events.txt
 create mode 100644 Documentation/libtracefs-files.txt
 create mode 100644 Documentation/libtracefs-instances-files.txt
 create mode 100644 Documentation/libtracefs-instances-manage.txt
 create mode 100644 Documentation/libtracefs-instances-utils.txt
 create mode 100644 Documentation/libtracefs-utils.txt
 create mode 100644 Documentation/libtracefs.txt
 create mode 100644 Documentation/manpage-1.72.xsl
 create mode 100644 Documentation/manpage-base.xsl
 create mode 100644 Documentation/manpage-bold-literal.xsl
 create mode 100644 Documentation/manpage-normal.xsl
 create mode 100644 Documentation/manpage-suppress-sp.xsl

-- 
2.28.0


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v2 1/8] libtracefs: Initial support for man pages
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Basic infrastructure for libtracefs man pages and the first man page:
 man libtracefs
with list of all library APIs.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/Makefile                 | 211 +++++++++++++++++++++++++
 Documentation/asciidoc.conf            | 120 ++++++++++++++
 Documentation/libtracefs.txt           |  84 ++++++++++
 Documentation/manpage-1.72.xsl         |  14 ++
 Documentation/manpage-base.xsl         |  35 ++++
 Documentation/manpage-bold-literal.xsl |  17 ++
 Documentation/manpage-normal.xsl       |  13 ++
 Documentation/manpage-suppress-sp.xsl  |  21 +++
 8 files changed, 515 insertions(+)
 create mode 100644 Documentation/Makefile
 create mode 100644 Documentation/asciidoc.conf
 create mode 100644 Documentation/libtracefs.txt
 create mode 100644 Documentation/manpage-1.72.xsl
 create mode 100644 Documentation/manpage-base.xsl
 create mode 100644 Documentation/manpage-bold-literal.xsl
 create mode 100644 Documentation/manpage-normal.xsl
 create mode 100644 Documentation/manpage-suppress-sp.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
new file mode 100644
index 0000000..e9212df
--- /dev/null
+++ b/Documentation/Makefile
@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: LGPL-2.1
+
+include $(src)/scripts/utils.mk
+
+
+# This Makefile and manpage XSL files were taken from libtraceevent
+# and modified for libtracefs.
+
+MAN3_TXT= \
+	$(wildcard libtracefs-*.txt) \
+	libtracefs.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/libtracefs-doc
+pdfdir?=$(prefix)/share/doc/libtracefs-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="libtracefs" -a manmanual="libtracefs 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 libtracefs-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 libtracefs-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
+
+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 install-html
+
+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 $(OUTPUT)*.3 $(DESTDIR)$(man3dir);
+
+install-man: check-man-tools man do-install-man
+
+do-install-html: html
+	$(call QUIET_INSTALL, Documentation-html) \
+		$(INSTALL) -d -m 755 $(DESTDIR)$(htmldir); \
+		$(INSTALL) -m 644 $(OUTPUT)*.html $(DESTDIR)$(htmldir);
+
+install-html: check-man-tools html do-install-html
+
+uninstall: uninstall-man uninstall-html
+
+uninstall-man:
+	$(call QUIET_UNINST, Documentation-man) \
+		$(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3))
+
+uninstall-html:
+	$(call QUIET_UNINST, Documentation-html) \
+		$(Q)$(RM) $(addprefix $(DESTDIR)$(htmldir)/,$(MAN_HTML))
+
+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) *.3
+
+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/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
new file mode 100644
index 0000000..0759571
--- /dev/null
+++ b/Documentation/asciidoc.conf
@@ -0,0 +1,120 @@
+## 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=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+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[]
+&#10;.ft C&#10;
+endif::doctype-manpage[]
+|
+ifdef::doctype-manpage[]
+&#10;.ft&#10;
+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">libtraceevent</refmiscinfo>
+<refmiscinfo class="version">{libtraceevent_version}</refmiscinfo>
+<refmiscinfo class="manual">libtraceevent Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <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[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[linktep-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
new file mode 100644
index 0000000..bd40f1f
--- /dev/null
+++ b/Documentation/libtracefs.txt
@@ -0,0 +1,84 @@
+libtracefs(3)
+=============
+
+NAME
+----
+libtracefs - Linux kernel trace file system library
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+Locations of tracing files and directories:
+	char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_);
+	void *tracefs_put_tracing_file*(char pass:[*]_name_);
+	const char pass:[*]*tracefs_tracing_dir*(void);
+
+Trace instances:
+	struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
+	int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
+	void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
+	bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
+	bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
+	bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
+	char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
+	char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_);
+	int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
+	char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_);
+	const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
+	int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_;
+	bool *tracefs_instance_exists*(const char pass:[*]_name_);
+
+Trace events:
+	char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
+	char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_);
+	int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_);
+	struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_);
+	struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
+	int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
+
+Trace helper functions:
+	void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
+	char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
+	char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
+--
+
+DESCRIPTION
+-----------
+The libtracefs(3) library provides APIs to access kernel trace file system.
+
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	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>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
new file mode 100644
index 0000000..b4d315c
--- /dev/null
+++ b/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">&#x2593;</xsl:param>
+<xsl:param name="git.docbook.dot"      >&#x2302;</xsl:param>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
new file mode 100644
index 0000000..a264fa6
--- /dev/null
+++ b/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&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</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&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 0000000..608eb5d
--- /dev/null
+++ b/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/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
new file mode 100644
index 0000000..a48f5b1
--- /dev/null
+++ b/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/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl
new file mode 100644
index 0000000..a63c763
--- /dev/null
+++ b/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>&#10;&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 1/8] libtracefs: Initial support for " Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21 16:00   ` Steven Rostedt
  2020-12-21  6:02 ` [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
                   ` (5 subsequent siblings)
  7 siblings, 1 reply; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_get_tracing_file()
tracefs_put_tracing_file()
tracefs_get_tracing_dir()
tracefs_find_tracing_dir()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 Documentation/libtracefs-files.txt

diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt
new file mode 100644
index 0000000..8bf9d75
--- /dev/null
+++ b/Documentation/libtracefs-files.txt
@@ -0,0 +1,97 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_tracing_dir -
+Find locations of trace directory and files.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_);
+void *tracefs_put_tracing_file*(char pass:[*]_name_);
+const char pass:[*]*tracefs_tracing_dir*(void);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to find the full path of the trace file
+system mount point and trace files in it.
+
+The _tracefs_get_tracing_file()_ function returns the full path of the
+file with given _name_ in the trace file system. The function works
+only with files in the trasefs main directory, it is not trace instance
+aware. It is recommended to use _tracefs_instance_get_file()_ and
+_tracefs_instance_get_dir()_ instead. The returned string must be freed
+with _tracefs_put_tracing_file()_.
+
+The _tracefs_put_tracing_file()_ function frees trace file name,
+returned by _tracefs_get_tracing_file()_.
+
+The _tracefs_tracing_dir()_ function returns the full path to the
+trace file system. In the first function call, the mount point of the
+tracing file system is located, cached and returned. It will mount it,
+if it is not mounted. On any subsequent call the cached path is returned.
+The return string must _not_ be freed.
+
+RETURN VALUE
+------------
+The _tracefs_get_tracing_file()_ function returns a string or NULL in case
+of an error. The returned string must be freed with _tracefs_put_tracing_file()_.
+
+The _tracefs_tracing_dir()_ function returns a constant string or NULL
+in case of an error. The returned string must _not_ be freed.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+...
+char *trace_on = tracefs_get_tracing_file("tracing_on");
+	if (trace_on) {
+		...
+		tracefs_put_tracing_file(trace_on);
+	}
+...
+const char *trace_dir = tracefs_tracing_dir();
+
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 1/8] libtracefs: Initial support for " Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21 16:18   ` Steven Rostedt
  2020-12-21  6:02 ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
                   ` (4 subsequent siblings)
  7 siblings, 1 reply; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_event_systems()
tracefs_system_events()
tracefs_iterate_raw_events()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-events.txt | 143 ++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 Documentation/libtracefs-events.txt

diff --git a/Documentation/libtracefs-events.txt b/Documentation/libtracefs-events.txt
new file mode 100644
index 0000000..3a51055
--- /dev/null
+++ b/Documentation/libtracefs-events.txt
@@ -0,0 +1,143 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_event_systems, tracefs_system_events, tracefs_iterate_raw_events -
+Work with trace systems and events.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
+char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_);
+int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_);
+
+--
+
+DESCRIPTION
+-----------
+Trace systems and events related APIs.
+
+The _tracefs_event_systems()_ function returns array of strings with the
+names of all registered trace systems, located in the given _tracing_dir_
+directory. This could be NULL or the location of the tracefs mount point
+for the trace systems of the local machine, or it may be a path to a copy
+of the tracefs directory from another machine. The last entry in the array
+is a NULL pointer. The array must be freed with _tracefs_list_free()_ API.
+
+The _tracefs_system_events()_ function returns array of strings with the
+names of all registered trace events for given trace system specified by
+_system_, located in the given _tracing_dir_ directory. This could be NULL
+or the location of the tracefs mount point for the trace systems of the
+local machine, or it may be a path to a copy of the tracefs directory
+from another machine. The last entry in the array as a NULL pointer.
+The array must be freed with _tracefs_list_free()_ API.
+
+The _tracefs_interate_raw_events()_ function will read the tracefs raw
+data buffers and call the specified _callback_ function for every event it
+encounters. An initialized _tep_ handler is required (See
+_tracefs_local_events_(3)). If _instance_ is NULL, then the toplevel
+tracefs buffer is used, otherwise the buffer for the corresponding
+_instance_ is read. To filter only on a subset of CPUs, _cpus_ and
+_cpu_size_ may be set to only call _callback_ with events that occurred on
+the CPUs specified, otherwise if _cpus_ is NULL then the _callback_
+function will be called for all events, and _cpu_size_ is ignored. The
+_callback_ function will be called with the following parameters: A
+pointer to a struct tep_event that corresponds to the type of event the
+record is; The record representing the event; The CPU that the event
+occurred on; and a pointer to user specified _context_. If the _callback_
+returns non-zero, the iteration stops.
+
+
+RETURN VALUE
+------------
+The _tracefs_event_systems()_ and __tracefs_system_events()_ functions return
+an array of strings. The last element in that array is a NULL pointer. The array
+must be freed with _tracefs_list_free()_ API. In case of an error, NULL is returned.
+
+The _tracefs_iterate_raw_events()_ function returns -1 in case of an error or
+0 otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+char **systems = tracefs_event_systems(NULL);
+
+	if (systems) {
+		int i = 0;
+		/* Got registered trace systems from the top trace instance */
+		while (systems[i]) {
+			char **events = tracefs_system_events(NULL, systems[i]);
+			if (events) {
+				/* Got registered events in system[i] from the top trace instance */
+				int j = 0;
+
+				while (events[j]) {
+					/* Got event[j] in system[i] from the top trace instance */
+					j++;
+				}
+				tracefs_list_free(events);
+			}
+			i++;
+		}
+		tracefs_list_free(systems);
+	}
+....
+static int records_walk(struct tep_event *tep, struct tep_record *record, int cpu, void *context)
+{
+	/* Got recorded event on cpu */
+	return 0;
+}
+...
+struct tep_event *tep = tracefs_local_events(NULL);
+
+	if (!tep) {
+		/* Failed to initialise tep handler with local events */
+		...
+	}
+	if (tracefs_iterate_raw_events(tep, NULL, NULL, 0, records_walk, NULL) < 0) {
+		/* Error walking through the recorded raw events */
+	}
+	tep_free(tep);
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
                   ` (2 preceding siblings ...)
  2020-12-21  6:02 ` [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21 16:51   ` Steven Rostedt
  2020-12-21  6:02 ` [PATCH v2 5/8] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
                   ` (3 subsequent siblings)
  7 siblings, 1 reply; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_instance_create()
tracefs_instance_destroy()
tracefs_instance_free()
tracefs_instance_is_new()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-manage.txt | 111 ++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 Documentation/libtracefs-instances-manage.txt

diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt
new file mode 100644
index 0000000..aca2161
--- /dev/null
+++ b/Documentation/libtracefs-instances-manage.txt
@@ -0,0 +1,111 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free,
+tracefs_instance_is_new - Manage trace instances.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
+int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
+void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
+bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
+
+--
+
+DESCRIPTION
+-----------
+This set of functions can be used to manage trace instances. A trace
+instance is a sub buffer used by the Linux tracing system. Given a unique
+name, the events enabled in an instance do not affect the main tracing
+system, nor other instances, as events enabled in the main tracing system
+or other instances do not affect the given instance.
+
+The _tracefs_instance_create()_ function allocates and initializes a new
+tracefs_instance structure and returns it. If the instance does not yet
+exist in the system, it will be created.
+
+The _tracefs_instance_destroy()_ frees the _instance_ structure, and will
+also remove the trace instance from the system.
+
+The _tracefs_instance_free()_ function frees the tracefs_instance structure,
+without removing the trace instance from the system.
+
+The _tracefs_instance_is_new()_ function checks if the given _instance_ is
+newly created by _tracefs_instance_create()_, or it has been in the system
+before that.
+
+RETURN VALUE
+------------
+The _tracefs_instance_create()_ function returns a pointer to a newly allocated
+tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or
+_tracefs_instance_free()_.
+
+The _tracefs_instance_destroy()_ function returns -1 in case of an error,
+or 0 otherwise.
+
+The _tracefs_instance_is_new()_ function returns true if the
+_tracefs_instance_create() that allocated _instance_ also created the
+trace instance in the system, or false if the trace instance already
+existed in the system when _instance_ was allocated by
+_tracefs_instance_create()_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst = tracefs_instance_create("foo");
+	if (!inst) {
+		/* Error creating a new trace instance */
+		...
+	}
+
+	...
+
+	if (tracefs_instance_is_new(inst))
+		tracefs_instance_destroy(inst);
+	else
+		tracefs_instance_free(inst);
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 5/8] libtracefs man pages: APIs for working with files in trace instances.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
                   ` (3 preceding siblings ...)
  2020-12-21  6:02 ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 6/8] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
                   ` (2 subsequent siblings)
  7 siblings, 0 replies; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_file_exists()
tracefs_dir_exists()
tracefs_instance_get_file()
tracefs_instance_get_dir()
tracefs_instance_file_write()
tracefs_instance_file_read()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-files.txt | 160 +++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 Documentation/libtracefs-instances-files.txt

diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt
new file mode 100644
index 0000000..7f9d381
--- /dev/null
+++ b/Documentation/libtracefs-instances-files.txt
@@ -0,0 +1,160 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_file_exists, tracefs_dir_exists, tracefs_instance_get_file,
+tracefs_instance_get_dir, tracefs_instance_file_write,
+tracefs_instance_file_read - Work with files in tracing instances.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
+bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
+char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
+char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_);
+int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
+char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_);
+
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to work with trace files in all trace instances.
+Each of these APIs take an _instance_ argument, that can be NULL to act
+on the top level instance. Otherwise, it acts on an instance created with
+*tracefs_insance_create*(3)
+
+The _tracefs_file_exists()_ function checks if a file with _name_ exists in _instance_.
+
+The _tracefs_dir_exists()_ function checks if a directory with _name_ exists in _instance_.
+
+The _tracefs_instance_get_file()_ function returns the full path of the file
+with given _name_ in _instance_. Note, it does not check if the file exists in
+the instance.
+
+The _tracefs_instance_get_dir()_ function  returns the full path of the directory
+with given _name_ in _instance_. Note, it does not check if the directory exists
+in the instance.
+
+The _tracefs_instance_file_write()_ function writes a string _str_ in a _file_ from
+the given _instance_, without the terminating NULL character.
+
+The _tracefs_instance_file_read()_ function reads the content of a _file_  from
+the given _instance_.
+
+RETURN VALUE
+------------
+The _tracefs_file_exists()_ and  _tracefs_dir_exists()_ functions return true if the
+file / directory exist in the given instance or false if it does not exist.
+
+The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions return
+a string or NULL in case of an error. The returned string must be freed with
+_tracefs_put_tracing_file()_.
+
+The _tracefs_instance_file_write()_ function returns the number of written bytes,
+or -1 in case of an error.
+
+The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated
+string, read from the file, or NULL in case of an error. The returned string must
+be freed with free().
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst = tracefs_instance_create("foo");
+	if (!inst) {
+		/* Error creating a new trace instance */
+		...
+	}
+
+	if (tracefs_file_exists(inst,"trace_clock")) {
+		/* The instance foo supports trace clock */
+		char *path, *clock;
+		int size;
+
+		path =  = tracefs_instance_get_file(inst, "trace_clock")
+		if (!path) {
+			/* Error getting the path to trace_clock file in instance foo */
+			...
+		}
+		...
+		tracefs_put_tracing_file(path);
+
+		clock = tracefs_instance_file_read(inst, "trace_clock", &size);
+		if (!clock) {
+			/* Failed to read trace_clock file in instance foo */
+			...
+		}
+		...
+		free(clock);
+
+		if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
+			/* Failed to set gloabl trace clock in instance foo */
+			...
+		}
+	} else {
+		/* The instance foo does not support trace clock */
+	}
+
+	if (tracefs_dir_exists(inst,"options")) {
+		/* The instance foo supports trace options */
+		char *path = tracefs_instance_get_file(inst, "options");
+		if (!path) {
+			/* Error getting the path to options directory in instance foo */
+			...
+		}
+
+		tracefs_put_tracing_file(path);
+	} else {
+		/* The instance foo does not support trace options */
+	}
+
+	...
+
+	if (tracefs_instance_is_new(inst))
+		tracefs_instance_destroy(inst);
+	else
+		tracefs_instance_free(inst);
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 6/8] libtracefs man pages: helper APIs for working with trace instances.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
                   ` (4 preceding siblings ...)
  2020-12-21  6:02 ` [PATCH v2 5/8] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
  2020-12-21  6:02 ` [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
  7 siblings, 0 replies; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_instance_get_name()
tracefs_instances_walk()
tracefs_instance_exists()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-instances-utils.txt | 112 +++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 Documentation/libtracefs-instances-utils.txt

diff --git a/Documentation/libtracefs-instances-utils.txt b/Documentation/libtracefs-instances-utils.txt
new file mode 100644
index 0000000..aa5efbd
--- /dev/null
+++ b/Documentation/libtracefs-instances-utils.txt
@@ -0,0 +1,112 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists -
+Helper functions for working with tracing instances.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_);
+int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_;
+bool *tracefs_instance_exists*(const char pass:[*]_name_);
+
+--
+
+DESCRIPTION
+-----------
+Helper functions for working with trace instances.
+
+The _tracefs_instance_get_name()_ function returns the name of the given _instance_.
+Note that the top instance has no name, the function returns NULL for it.
+
+The _tracefs_instances_walk()_ function walks through all configured tracing
+instances in the system and calls _callback_ for each one of them. The _context_
+argument is passed to the _callback_, together with the instance name. If the
+_callback_ returns non-zero, the iteration stops. Note, the _callback_ is not
+called for the top top instance.
+
+The _tracefs_instance_exists()_ function checks if an instance with the given
+_name_ exists in the system.
+
+RETURN VALUE
+------------
+The _tracefs_instance_get_name()_ returns a string or NULL in case of the top
+instance. The returned string must _not_ be freed.
+
+The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1
+if the iteration was stopped by the _callback_, or -1 in case of an error.
+
+The _tracefs_instance_exists()_ returns true if an instance with the given name
+exists in the system or false otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+struct tracefs_instance *inst;
+....
+char *name = tracefs_instance_get_name(inst);
+
+	if(name) {
+		/* Got name of the instance */
+	}
+
+...
+static int instance_walk(char *name, void *context)
+{
+	/* Got instance with name */
+	return 0;
+}
+...
+	if (tracefs_instances_walk(instance_walk, NULL) < 0) {
+		/* Error walking through the instances */
+	}
+...
+	if (tracefs_instance_exists("foo")) {
+		/* There is instance with name foo in the system */
+	} else {
+		/* There is no instance with name foo in the system */
+	}
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
                   ` (5 preceding siblings ...)
  2020-12-21  6:02 ` [PATCH v2 6/8] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21 17:19   ` Steven Rostedt
  2020-12-21  6:02 ` [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
  7 siblings, 1 reply; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_local_events()
tracefs_local_events_system()
tracefs_fill_local_events()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-events-tep.txt | 131 ++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 Documentation/libtracefs-events-tep.txt

diff --git a/Documentation/libtracefs-events-tep.txt b/Documentation/libtracefs-events-tep.txt
new file mode 100644
index 0000000..a01ce0e
--- /dev/null
+++ b/Documentation/libtracefs-events-tep.txt
@@ -0,0 +1,131 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events -
+Initialize a tep handler with trace events from the local system.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+*#include <event-parse.h>*
+
+struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_);
+struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
+int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
+
+--
+
+DESCRIPTION
+-----------
+Functions for initializing a tep handler with trace events from the local system.
+
+The _tracefs_local_events()_ function allocates a new _tep_ handler and
+initializes it with events from all trace systems, located in the given
+_tracing_dir_ directory. This could be NULL or tracefs mount point, for
+trace events in top instance, or full path to a trace instance, for trace
+events in that instance.
+
+The _tracefs_local_events_system()_ function allocates a new _tep_ handler
+and initializes it with events from specified trace systems _sys_names_,
+located in the given _tracing_dir_ directory. This could be NULL or tracefs
+mount point, for trace events in top instance, or full path to a trace instance,
+for trace events in that instance. The _sys_names_ argument is an array of
+trace system names, that will be used for _tep_ handler initialization.
+The last element in that array must be a NULL pointer.
+
+The _tracefs_fill_local_events()_ function initializes already allocated _tep_
+handler with events from all trace systems, located in the given _tracing_dir_
+directory. This could be NULL or tracefs mount point, for trace events in
+the top instance, or full path to a trace instance, for trace events in that
+instance. The _tep_ argument must be a pointer to already allocated tep
+handler, that is going to be initialized. The _parsing_failures_ argument
+could be NULL or a pointer to an integer, where the number of failures while
+parsing the event files are returned.
+
+RETURN VALUE
+------------
+The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions
+return pointer to allocated and initialized _tep_ handler, or NULL in
+case of an error. The returned _tep_ handler must be freed with _tep_free()_.
+
+The _tracefs_fill_local_events()_ function returns -1 in case of an error or
+0 otherwise.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+#include <event-parse.h>
+
+struct tep_event *tep;
+...
+	tep = tracefs_local_events(NULL);
+	if (!tep) {
+		/* Failed to initialise tep handler with local events from top instance */
+		...
+	}
+...
+	tep_free(tep);
+...
+	const char *systems[] = {"ftrace", "irq", NULL};
+	tep = tracefs_local_events_system(NULL, systems);
+	if (!tep) {
+		/* Failed to initialise tep handler with local events from
+		 * ftrace and irq systems in top instance.
+		 */
+		...
+	}
+...
+	tep_free(tep);
+...
+	int parsing_failures;
+	tep = tep_alloc();
+	if (!tep) {
+		/* Failed to allocate a tep handler */
+		...
+	}
+	if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) {
+		/* Failed to initialise tep handler with local events from top instance */
+	}
+...
+	tep_free(tep);
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system.
  2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
                   ` (6 preceding siblings ...)
  2020-12-21  6:02 ` [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
@ 2020-12-21  6:02 ` Tzvetomir Stoyanov (VMware)
  2020-12-21 17:21   ` Steven Rostedt
  7 siblings, 1 reply; 14+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-21  6:02 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
tracefs_tracers()
tracefs_get_clock()
tracefs_list_free()

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/libtracefs-utils.txt | 103 +++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 Documentation/libtracefs-utils.txt

diff --git a/Documentation/libtracefs-utils.txt b/Documentation/libtracefs-utils.txt
new file mode 100644
index 0000000..86dd754
--- /dev/null
+++ b/Documentation/libtracefs-utils.txt
@@ -0,0 +1,103 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_tracers, tracefs_get_clock, tracefs_list_free -
+Helper functions for working with trace file system.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+
+char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
+char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
+void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
+--
+
+DESCRIPTION
+-----------
+Various useful functions for working with trace file system.
+
+The _tracefs_tracers()_ function returns array of strings with the
+names of supported tracer plugins, located in the given _tracing_dir_ directory.
+This could be NULL or tracefs mount point, for trace systems in top instance,
+or full path to a trace instance, for trace systems in that instance.
+The last entry in the array as a NULL pointer. The array must
+be freed with _tracefs_list_free()_ API.
+
+The _tracefs_get_clock()_ function returns name of the current trace clock,
+used in the given _instance_. If _instance_ is NULL, the clock of the main
+trace instance is returned. The returned string must be freed with free().
+
+The _tracefs_list_free()_ function frees an array of strings, returned by
+_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_
+APIs.
+
+RETURN VALUE
+------------
+The _tracefs_tracers()_ returns array of strings. The last element in that
+array is a NULL pointer. The array must be freed with _tracefs_list_free()_ API.
+In case of an error, NULL is returned.
+
+The _tracefs_get_clock()_ returns string, that must be freed with free(), or NULL
+in case of an error.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <tracefs.h>
+
+char **tracers = tracefs_tracers(NULL);
+
+	if (tracers) {
+		/* Got tracer plugins from the top trace instance */
+		...
+		tracefs_list_free(tracers);
+	}
+....
+char *clock = tracefs_get_clock(NULL);
+
+	if (clock) {
+		/* Got current trace clock of the top trace instance */
+		...
+		free(clock);
+	}
+--
+FILES
+-----
+[verse]
+--
+*tracefs.h*
+	Header file to include in order to have access to the library APIs.
+*-ltracefs*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtracefs is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
\ No newline at end of file
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files.
  2020-12-21  6:02 ` [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
@ 2020-12-21 16:00   ` Steven Rostedt
  0 siblings, 0 replies; 14+ messages in thread
From: Steven Rostedt @ 2020-12-21 16:00 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel

On Mon, 21 Dec 2020 08:02:46 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> Documented APIs:
> tracefs_get_tracing_file()
> tracefs_put_tracing_file()
> tracefs_get_tracing_dir()
> tracefs_find_tracing_dir()

The commit log was not updated. I'll fix this.

-- Steve

> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++
>  1 file changed, 97 insertions(+)
>  create mode 100644 Documentation/libtracefs-files.txt
> 
> diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events.
  2020-12-21  6:02 ` [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
@ 2020-12-21 16:18   ` Steven Rostedt
  0 siblings, 0 replies; 14+ messages in thread
From: Steven Rostedt @ 2020-12-21 16:18 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel

On Mon, 21 Dec 2020 08:02:47 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
> +char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_);
> +int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_);
> +
> +--
> +
> +DESCRIPTION
> +-----------
> +Trace systems and events related APIs.
> +
> +The _tracefs_event_systems()_ function returns array of strings with the
> +names of all registered trace systems, located in the given _tracing_dir_
> +directory. This could be NULL or the location of the tracefs mount point
> +for the trace systems of the local machine, or it may be a path to a copy
> +of the tracefs directory from another machine. The last entry in the array
> +is a NULL pointer. The array must be freed with _tracefs_list_free()_ API.
> +
> +The _tracefs_system_events()_ function returns array of strings with the
> +names of all registered trace events for given trace system specified by
> +_system_, located in the given _tracing_dir_ directory. This could be NULL
> +or the location of the tracefs mount point for the trace systems of the
> +local machine, or it may be a path to a copy of the tracefs directory
> +from another machine. The last entry in the array as a NULL pointer.
> +The array must be freed with _tracefs_list_free()_ API.
> +
> +The _tracefs_interate_raw_events()_ function will read the tracefs raw
> +data buffers and call the specified _callback_ function for every event it
> +encounters. An initialized _tep_ handler is required (See
> +_tracefs_local_events_(3)). If _instance_ is NULL, then the toplevel
> +tracefs buffer is used, otherwise the buffer for the corresponding
> +_instance_ is read. To filter only on a subset of CPUs, _cpus_ and
> +_cpu_size_ may be set to only call _callback_ with events that occurred on
> +the CPUs specified, otherwise if _cpus_ is NULL then the _callback_
> +function will be called for all events, and _cpu_size_ is ignored. The
> +_callback_ function will be called with the following parameters: A
> +pointer to a struct tep_event that corresponds to the type of event the
> +record is; The record representing the event; The CPU that the event
> +occurred on; and a pointer to user specified _context_. If the _callback_

I changed "_context_" to "_callback_context_" as it should match the name
used above in the function prototype.

-- Steve

> +returns non-zero, the iteration stops.

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances.
  2020-12-21  6:02 ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
@ 2020-12-21 16:51   ` Steven Rostedt
  0 siblings, 0 replies; 14+ messages in thread
From: Steven Rostedt @ 2020-12-21 16:51 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel

On Mon, 21 Dec 2020 08:02:48 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +RETURN VALUE
> +------------
> +The _tracefs_instance_create()_ function returns a pointer to a newly allocated
> +tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or
> +_tracefs_instance_free()_.
> +
> +The _tracefs_instance_destroy()_ function returns -1 in case of an error,
> +or 0 otherwise.
> +
> +The _tracefs_instance_is_new()_ function returns true if the
> +_tracefs_instance_create() that allocated _instance_ also created the

Missing underscore after "_tracefs_instance_create()", which caused a
run-away underlining. I fixed it.

-- Steve


> +trace instance in the system, or false if the trace instance already
> +existed in the system when _instance_ was allocated by
> +_tracefs_instance_create()_.
> +

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
  2020-12-21  6:02 ` [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
@ 2020-12-21 17:19   ` Steven Rostedt
  0 siblings, 0 replies; 14+ messages in thread
From: Steven Rostedt @ 2020-12-21 17:19 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel

I've applied everything up to this patch, but this patch will need to be
updated more than just a tweak, so I'm not pulling it in.


On Mon, 21 Dec 2020 08:02:51 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> Documented APIs:
> tracefs_local_events()
> tracefs_local_events_system()
> tracefs_fill_local_events()
> 
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
>  Documentation/libtracefs-events-tep.txt | 131 ++++++++++++++++++++++++
>  1 file changed, 131 insertions(+)
>  create mode 100644 Documentation/libtracefs-events-tep.txt
> 
> diff --git a/Documentation/libtracefs-events-tep.txt b/Documentation/libtracefs-events-tep.txt
> new file mode 100644
> index 0000000..a01ce0e
> --- /dev/null
> +++ b/Documentation/libtracefs-events-tep.txt
> @@ -0,0 +1,131 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events -
> +Initialize a tep handler with trace events from the local system.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +*#include <event-parse.h>*

No need for the "event-parse.h"

> +
> +struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_);
> +struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_);
> +int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_);
> +
> +--
> +
> +DESCRIPTION
> +-----------
> +Functions for initializing a tep handler with trace events from the local system.
> +
> +The _tracefs_local_events()_ function allocates a new _tep_ handler and
> +initializes it with events from all trace systems, located in the given
> +_tracing_dir_ directory. This could be NULL or tracefs mount point, for
> +trace events in top instance, or full path to a trace instance, for trace
> +events in that instance.

The definition of _tracing_dir_ needs to be updated to what the other
patches were. They shouldn't mention the full path to a trace instance.



> +
> +The _tracefs_local_events_system()_ function allocates a new _tep_ handler
> +and initializes it with events from specified trace systems _sys_names_,
> +located in the given _tracing_dir_ directory. This could be NULL or tracefs
> +mount point, for trace events in top instance, or full path to a trace instance,
> +for trace events in that instance. The _sys_names_ argument is an array of
> +trace system names, that will be used for _tep_ handler initialization.
> +The last element in that array must be a NULL pointer.
> +
> +The _tracefs_fill_local_events()_ function initializes already allocated _tep_
> +handler with events from all trace systems, located in the given _tracing_dir_
> +directory. This could be NULL or tracefs mount point, for trace events in
> +the top instance, or full path to a trace instance, for trace events in that
> +instance. The _tep_ argument must be a pointer to already allocated tep
> +handler, that is going to be initialized. The _parsing_failures_ argument
> +could be NULL or a pointer to an integer, where the number of failures while
> +parsing the event files are returned.

Same with the above two.

> +
> +RETURN VALUE
> +------------
> +The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions
> +return pointer to allocated and initialized _tep_ handler, or NULL in
> +case of an error. The returned _tep_ handler must be freed with _tep_free()_.

 "must be freed with _tep_free(3)_" 

As there is a man page for that one.

Thanks!

-- Steve


> +
> +The _tracefs_fill_local_events()_ function returns -1 in case of an error or
> +0 otherwise.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <tracefs.h>
> +#include <event-parse.h>
> +
> +struct tep_event *tep;
> +...
> +	tep = tracefs_local_events(NULL);
> +	if (!tep) {
> +		/* Failed to initialise tep handler with local events from top instance */
> +		...
> +	}
> +...
> +	tep_free(tep);
> +...
> +	const char *systems[] = {"ftrace", "irq", NULL};
> +	tep = tracefs_local_events_system(NULL, systems);
> +	if (!tep) {
> +		/* Failed to initialise tep handler with local events from
> +		 * ftrace and irq systems in top instance.
> +		 */
> +		...
> +	}
> +...
> +	tep_free(tep);
> +...
> +	int parsing_failures;
> +	tep = tep_alloc();
> +	if (!tep) {
> +		/* Failed to allocate a tep handler */
> +		...
> +	}
> +	if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) {
> +		/* Failed to initialise tep handler with local events from top instance */
> +	}
> +...
> +	tep_free(tep);
> +--
> +FILES
> +-----
> +[verse]
> +--
> +*tracefs.h*
> +	Header file to include in order to have access to the library APIs.
> +*-ltracefs*
> +	Linker switch to add when building a program that uses the library.
> +--
> +
> +SEE ALSO
> +--------
> +_libtracefs(3)_,
> +_libtraceevent(3)_,
> +_trace-cmd(1)_
> +
> +AUTHOR
> +------
> +[verse]
> +--
> +*Steven Rostedt* <rostedt@goodmis.org>
> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to  <linux-trace-devel@vger.kernel.org>
> +
> +LICENSE
> +-------
> +libtracefs is Free Software licensed under the GNU LGPL 2.1
> +
> +RESOURCES
> +---------
> +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
> \ No newline at end of file


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system.
  2020-12-21  6:02 ` [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
@ 2020-12-21 17:21   ` Steven Rostedt
  0 siblings, 0 replies; 14+ messages in thread
From: Steven Rostedt @ 2020-12-21 17:21 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel

On Mon, 21 Dec 2020 08:02:52 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +DESCRIPTION
> +-----------
> +Various useful functions for working with trace file system.
> +
> +The _tracefs_tracers()_ function returns array of strings with the
> +names of supported tracer plugins, located in the given _tracing_dir_ directory.
> +This could be NULL or tracefs mount point, for trace systems in top instance,
> +or full path to a trace instance, for trace systems in that instance.
> +The last entry in the array as a NULL pointer. The array must
> +be freed with _tracefs_list_free()_ API.

The description above needs to be updated as well.

-- Steve

> +
> +The _tracefs_get_clock()_ function returns name of the current trace clock,
> +used in the given _instance_. If _instance_ is NULL, the clock of the main
> +trace instance is returned. The returned string must be freed with free().
> +
> +The _tracefs_list_free()_ function frees an array of strings, returned by
> +_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_
> +APIs.
> +

^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2020-12-21 17:22 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-21  6:02 [PATCH v2 0/8] libtracefs man pages Tzvetomir Stoyanov (VMware)
2020-12-21  6:02 ` [PATCH v2 1/8] libtracefs: Initial support for " Tzvetomir Stoyanov (VMware)
2020-12-21  6:02 ` [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
2020-12-21 16:00   ` Steven Rostedt
2020-12-21  6:02 ` [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
2020-12-21 16:18   ` Steven Rostedt
2020-12-21  6:02 ` [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
2020-12-21 16:51   ` Steven Rostedt
2020-12-21  6:02 ` [PATCH v2 5/8] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
2020-12-21  6:02 ` [PATCH v2 6/8] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
2020-12-21  6:02 ` [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
2020-12-21 17:19   ` Steven Rostedt
2020-12-21  6:02 ` [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
2020-12-21 17:21   ` Steven Rostedt

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).