* [PATCH 1/9] libtracefs: Remove doc_gui targets
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 19:24 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 2/9] libtracefs: Initial support for man pages Tzvetomir Stoyanov (VMware)
` (7 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
There is no gui in libtracefs, removed forgotten targets for building
gui documentation.
Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
Makefile | 9 ---------
1 file changed, 9 deletions(-)
diff --git a/Makefile b/Makefile
index a7d5808..7460d4d 100644
--- a/Makefile
+++ b/Makefile
@@ -255,19 +255,10 @@ install_pkgconfig: $(PKG_CONFIG_FILE)
doc:
$(MAKE) -C $(src)/Documentation all
-doc_gui:
- $(MAKE) -C $(kshark-dir)/Documentation all
-
-
doc_clean:
$(MAKE) -C $(src)/Documentation clean
-doc_gui_clean:
- $(MAKE) -C $(kshark-dir)/Documentation clean
-
install_doc:
$(MAKE) -C $(src)/Documentation install
-install_doc_gui:
- $(MAKE) -C $(kshark-dir)/Documentation install
define build_uninstall_script
$(Q)mkdir $(BUILD_OUTPUT)/tmp_build
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [PATCH 1/9] libtracefs: Remove doc_gui targets
2020-12-17 9:46 ` [PATCH 1/9] libtracefs: Remove doc_gui targets Tzvetomir Stoyanov (VMware)
@ 2020-12-18 19:24 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 19:24 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:18 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> There is no gui in libtracefs, removed forgotten targets for building
> gui documentation.
>
I already applied a similar patch. No need for this one.
-- Steve
> Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
> ---
> Makefile | 9 ---------
> 1 file changed, 9 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index a7d5808..7460d4d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -255,19 +255,10 @@ install_pkgconfig: $(PKG_CONFIG_FILE)
>
> doc:
> $(MAKE) -C $(src)/Documentation all
> -doc_gui:
> - $(MAKE) -C $(kshark-dir)/Documentation all
> -
> -
> doc_clean:
> $(MAKE) -C $(src)/Documentation clean
> -doc_gui_clean:
> - $(MAKE) -C $(kshark-dir)/Documentation clean
> -
> install_doc:
> $(MAKE) -C $(src)/Documentation install
> -install_doc_gui:
> - $(MAKE) -C $(kshark-dir)/Documentation install
>
> define build_uninstall_script
> $(Q)mkdir $(BUILD_OUTPUT)/tmp_build
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 2/9] libtracefs: Initial support for man pages
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
2020-12-17 9:46 ` [PATCH 1/9] libtracefs: Remove doc_gui targets Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 18:49 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
` (6 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 86 ++++++++++
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, 517 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=*
+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">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..c7a4d54
--- /dev/null
+++ b/Documentation/libtracefs.txt
@@ -0,0 +1,86 @@
+libtracefs(3)
+=============
+
+NAME
+----
+libtracefs - Linux kernel trace file system library
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+*#include <event-parse.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_get_tracing_dir*(void);
+ char pass:[*]*tracefs_find_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">▓</xsl:param>
+<xsl:param name="git.docbook.dot" >⌂</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 </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/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> </xsl:text>
+ </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread* Re: [PATCH 2/9] libtracefs: Initial support for man pages
2020-12-17 9:46 ` [PATCH 2/9] libtracefs: Initial support for man pages Tzvetomir Stoyanov (VMware)
@ 2020-12-18 18:49 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 18:49 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:19 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +*#include <event-parse.h>*
tracefs.h already includes event-parse.h, and when it is installed, it's
not in the standard search path (unless you add pkg-config libtraceevent).
I would remove the reference to event-parse.h.
-- Steve
> +
> +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_get_tracing_dir*(void);
> + char pass:[*]*tracefs_find_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_);
> +--
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
2020-12-17 9:46 ` [PATCH 1/9] libtracefs: Remove doc_gui targets Tzvetomir Stoyanov (VMware)
2020-12-17 9:46 ` [PATCH 2/9] libtracefs: Initial support for man pages Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 18:55 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 4/9] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
` (5 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 111 +++++++++++++++++++++++++++++
1 file changed, 111 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..b288892
--- /dev/null
+++ b/Documentation/libtracefs-files.txt
@@ -0,0 +1,111 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_get_tracing_dir,
+tracefs_find_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_get_tracing_dir*(void);
+char pass:[*]*tracefs_find_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_find_tracing_dir()_ function finds the mount point of the
+trace file system and returns a full path to it. If the file system is
+not mounted, it will mount it. The returned string must be freed.
+
+The _tracefs_get_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 minted. 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_find_tracing_dir()_ function returns a string or NULL in case
+of an error. The returned string must be freed.
+
+The _tracefs_get_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);
+ }
+...
+char *trace_dir = tracefs_find_tracing_dir();
+ if (trace_dir) {
+ ...
+ free(trace_dir);
+ }
+...
+const char *trace_dir = tracefs_get_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] 20+ messages in thread* Re: [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.
2020-12-17 9:46 ` [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
@ 2020-12-18 18:55 ` Steven Rostedt
2020-12-21 3:44 ` Tzvetomir Stoyanov
0 siblings, 1 reply; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 18:55 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:20 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> +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_find_tracing_dir()_ function finds the mount point of the
> +trace file system and returns a full path to it. If the file system is
> +not mounted, it will mount it. The returned string must be freed.
How should it be freed?
> +
> +The _tracefs_get_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 minted. 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_find_tracing_dir()_ function returns a string or NULL in case
> +of an error. The returned string must be freed.
Should state how it should be freed. tracefs_put_tracing_file() or free() ?
If it is free(), then stating:
"The returned string must be freed with free()"
is fine.
> +
> +The _tracefs_get_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);
> + }
> +...
> +char *trace_dir = tracefs_find_tracing_dir();
> + if (trace_dir) {
> + ...
> + free(trace_dir);
> + }
> +...
> +const char *trace_dir = tracefs_get_tracing_dir();
> +
Not a very useful example ;-) We we can fix examples at a later time. I
plan on writing a lot of example code to post, and some can make their way
into the man pages.
-- Steve
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.
2020-12-18 18:55 ` Steven Rostedt
@ 2020-12-21 3:44 ` Tzvetomir Stoyanov
2020-12-21 4:10 ` Steven Rostedt
0 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov @ 2020-12-21 3:44 UTC (permalink / raw)
To: Steven Rostedt; +Cc: Linux Trace Devel
On Fri, Dec 18, 2020 at 8:55 PM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Thu, 17 Dec 2020 11:46:20 +0200
> "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
>
> > +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_find_tracing_dir()_ function finds the mount point of the
> > +trace file system and returns a full path to it. If the file system is
> > +not mounted, it will mount it. The returned string must be freed.
>
> How should it be freed?
I'll add " with free()" in the next version of the patch, but I was
wondering if the
user should use "tracefs_put_tracing_file()" instead ? These APIs are not
consistent, may be they should be renamed. Now we have:
tracefs_get_tracing_file() / tracefs_put_tracing_file()
tracefs_get_tracing_dir() / returns static, must not be feed.
tracefs_find_tracing_dir() / free()
>
> > +
> > +The _tracefs_get_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 minted. 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_find_tracing_dir()_ function returns a string or NULL in case
> > +of an error. The returned string must be freed.
>
> Should state how it should be freed. tracefs_put_tracing_file() or free() ?
>
> If it is free(), then stating:
>
> "The returned string must be freed with free()"
>
> is fine.
>
> > +
> > +The _tracefs_get_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);
> > + }
> > +...
> > +char *trace_dir = tracefs_find_tracing_dir();
> > + if (trace_dir) {
> > + ...
> > + free(trace_dir);
> > + }
> > +...
> > +const char *trace_dir = tracefs_get_tracing_dir();
> > +
>
> Not a very useful example ;-) We we can fix examples at a later time. I
> plan on writing a lot of example code to post, and some can make their way
> into the man pages.
>
> -- Steve
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.
2020-12-21 3:44 ` Tzvetomir Stoyanov
@ 2020-12-21 4:10 ` Steven Rostedt
2020-12-21 5:03 ` Tzvetomir Stoyanov
0 siblings, 1 reply; 20+ messages in thread
From: Steven Rostedt @ 2020-12-21 4:10 UTC (permalink / raw)
To: Tzvetomir Stoyanov; +Cc: Linux Trace Devel
On Mon, 21 Dec 2020 05:44:45 +0200
Tzvetomir Stoyanov <tz.stoyanov@gmail.com> wrote:
> > How should it be freed?
> I'll add " with free()" in the next version of the patch, but I was
> wondering if the
> user should use "tracefs_put_tracing_file()" instead ? These APIs are not
> consistent, may be they should be renamed.
Good point.
> Now we have:
>
> tracefs_get_tracing_file() / tracefs_put_tracing_file()
> tracefs_get_tracing_dir() / returns static, must not be feed.
> tracefs_find_tracing_dir() / free()
Perhaps we should change tracefs_get_tracing_dir() to simply:
tracefs_tracing_dir().
Hmm, what's the difference between "tracefs_find_tracing_dir() and
tracefs_get_tracing_dir() (or what we will call tracefs_tracing_dir())?
The only difference I see from the two descriptions is that one returns
a cached string and the other returns just an allocated string. Do we
even need tracefs_find_tracing_dir()?
>
>
> >
> > > +
> > > +The _tracefs_get_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 minted. On any subsequent call the cached path is returned.
Just noticed the above typo. s/minted/mounted/
Although, I wonder if a minted dir tastes good? ;-)
-- Steve
> > > +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_find_tracing_dir()_ function returns a string or NULL in case
> > > +of an error. The returned string must be freed.
> >
> > Should state how it should be freed. tracefs_put_tracing_file() or free() ?
> >
> > If it is free(), then stating:
> >
> > "The returned string must be freed with free()"
> >
> > is fine.
> >
> > > +
> > > +The _tracefs_get_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);
> > > + }
> > > +...
> > > +char *trace_dir = tracefs_find_tracing_dir();
> > > + if (trace_dir) {
> > > + ...
> > > + free(trace_dir);
> > > + }
> > > +...
> > > +const char *trace_dir = tracefs_get_tracing_dir();
> > > +
> >
> > Not a very useful example ;-) We we can fix examples at a later time. I
> > plan on writing a lot of example code to post, and some can make their way
> > into the man pages.
> >
> > -- Steve
>
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files.
2020-12-21 4:10 ` Steven Rostedt
@ 2020-12-21 5:03 ` Tzvetomir Stoyanov
0 siblings, 0 replies; 20+ messages in thread
From: Tzvetomir Stoyanov @ 2020-12-21 5:03 UTC (permalink / raw)
To: Steven Rostedt; +Cc: Linux Trace Devel
On Mon, Dec 21, 2020 at 6:10 AM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Mon, 21 Dec 2020 05:44:45 +0200
> Tzvetomir Stoyanov <tz.stoyanov@gmail.com> wrote:
>
> > > How should it be freed?
> > I'll add " with free()" in the next version of the patch, but I was
> > wondering if the
> > user should use "tracefs_put_tracing_file()" instead ? These APIs are not
> > consistent, may be they should be renamed.
>
> Good point.
>
> > Now we have:
> >
> > tracefs_get_tracing_file() / tracefs_put_tracing_file()
> > tracefs_get_tracing_dir() / returns static, must not be feed.
> > tracefs_find_tracing_dir() / free()
>
> Perhaps we should change tracefs_get_tracing_dir() to simply:
> tracefs_tracing_dir().
>
>
> Hmm, what's the difference between "tracefs_find_tracing_dir() and
> tracefs_get_tracing_dir() (or what we will call tracefs_tracing_dir())?
>
> The only difference I see from the two descriptions is that one returns
> a cached string and the other returns just an allocated string. Do we
> even need tracefs_find_tracing_dir()?
The tracefs_find_tracing_dir() function is used in trace-cmd, but I agree that
it can be removed. I'll rename tracefs_get_tracing_dir() to
tracefs_tracing_dir()
and remove tracefs_find_tracing_dir() API. Going to change trace-cmd to use
only tracefs_tracing_dir() API.
>
> >
> >
> > >
> > > > +
> > > > +The _tracefs_get_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 minted. On any subsequent call the cached path is returned.
>
> Just noticed the above typo. s/minted/mounted/
>
> Although, I wonder if a minted dir tastes good? ;-)
>
> -- Steve
>
> > > > +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_find_tracing_dir()_ function returns a string or NULL in case
> > > > +of an error. The returned string must be freed.
> > >
> > > Should state how it should be freed. tracefs_put_tracing_file() or free() ?
> > >
> > > If it is free(), then stating:
> > >
> > > "The returned string must be freed with free()"
> > >
> > > is fine.
> > >
> > > > +
> > > > +The _tracefs_get_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);
> > > > + }
> > > > +...
> > > > +char *trace_dir = tracefs_find_tracing_dir();
> > > > + if (trace_dir) {
> > > > + ...
> > > > + free(trace_dir);
> > > > + }
> > > > +...
> > > > +const char *trace_dir = tracefs_get_tracing_dir();
> > > > +
> > >
> > > Not a very useful example ;-) We we can fix examples at a later time. I
> > > plan on writing a lot of example code to post, and some can make their way
> > > into the man pages.
> > >
> > > -- Steve
> >
> >
> >
>
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 4/9] libtracefs man pages: APIs for working with trace systems and events.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (2 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 3/9] libtracefs man pages: APIs for locating trace directory and files Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 19:23 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 5/9] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
` (4 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 140 ++++++++++++++++++++++++++++
1 file changed, 140 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..1fa4674
--- /dev/null
+++ b/Documentation/libtracefs-events.txt
@@ -0,0 +1,140 @@
+libtracefs(3)
+=============
+
+NAME
+----
+tracefs_event_systems, tracefs_system_events, tracefs_iterate_raw_events -
+Work with trace systems and events.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <tracefs.h>*
+*#include <event-parse.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 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 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 all registered trace events for given trace system, 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 last entry in the array as a NULL
+pointer. The array must be freed with _tracefs_list_free()_ API.
+
+The _tracefs_iterate_raw_events()_ function iterates through all recorded
+events in the raw trace ring buffer. It requires an initialized _tep_
+handler. The ring buffer being iterated is in the given _instance_, or
+in the top instance if _instance_ is NULL. It can filter events
+for given _cpus_ only, a CPU mask of _cpu_size_ size, or walk through all
+recorded events, if _cpus_ is a NULL pointer. The _callback_ is called for
+every recorded event from the ring buffer. The _callback_context_ parameter
+is passed to the _callback_. Parameters of the _callback_ are _tep_ event
+handler; a pointer to recorded event, _struct tep_record_; the _cpu_ on
+which the event had been happened and the user specified _callback_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>
+#include <event-parse.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] 20+ messages in thread* Re: [PATCH 4/9] libtracefs man pages: APIs for working with trace systems and events.
2020-12-17 9:46 ` [PATCH 4/9] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
@ 2020-12-18 19:23 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 19:23 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:21 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> --- /dev/null
> +++ b/Documentation/libtracefs-events.txt
> @@ -0,0 +1,140 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_event_systems, tracefs_system_events, tracefs_iterate_raw_events -
> +Work with trace systems and events.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +*#include <event-parse.h>*
Let's remove all references of event-parse.h, as tracefs.h should already
handle that.
> +
> +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 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 is a NULL pointer. The array must
> +be freed with _tracefs_list_free()_ API.
Since an instance always has the same event directory structure as the top
instance (and soon this will be even more guaranteed, when they will all
share the same directory internally), I would leave out the mentioning of
the path to the trace systems of an instance.
What I would mention, is that the path may be of a copy of a directory (for
example, copying an event directory from another machine).
"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 _tracefs_system_events()_ function returns array of strings with the
> +names all registered trace events for given trace system, located in the
"given trace system specified by _system_, 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 last entry in the array as a NULL
> +pointer. The array must be freed with _tracefs_list_free()_ API.
Same update as for tracefs_event_systems().
> +
> +The _tracefs_iterate_raw_events()_ function iterates through all recorded
> +events in the raw trace ring buffer. It requires an initialized _tep_
> +handler. The ring buffer being iterated is in the given _instance_, or
> +in the top instance if _instance_ is NULL. It can filter events
> +for given _cpus_ only, a CPU mask of _cpu_size_ size, or walk through all
> +recorded events, if _cpus_ is a NULL pointer. The _callback_ is called for
> +every recorded event from the ring buffer. The _callback_context_ parameter
> +is passed to the _callback_. Parameters of the _callback_ are _tep_ event
> +handler; a pointer to recorded event, _struct tep_record_; the _cpu_ on
> +which the event had been happened and the user specified _callback_context_.
> +If the _callback_ returns non-zero, the iteration stops.
I would reword the above differently, as the above is too close to the
implementation doesn't really explain its purpose.
"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 _context_."
> +
> +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>
> +#include <event-parse.h>
No need for the event-parse.h.
-- Steve
> +
> +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
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 5/9] libtracefs man pages: APIs for managing trace instances.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (3 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 4/9] libtracefs man pages: APIs for working with trace systems and events Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 20:08 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 6/9] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
` (3 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 104 ++++++++++++++++++
1 file changed, 104 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..ca08269
--- /dev/null
+++ b/Documentation/libtracefs-instances-manage.txt
@@ -0,0 +1,104 @@
+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.
+
+The _tracefs_instance_create()_ function creates a new trace instance with given
+_name_, if it does not already exist in the system. It allocates and initializes
+a new tracefs_instance structure and returns it.
+
+The _tracefs_instance_destroy()_ destroys the trace _instance_ and frees the
+tracefs_instance structure.
+
+The _tracefs_instance_free()_ function frees the tracefs_instance structure,
+without destroying the trace instance.
+
+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 instance is
+created by _tracefs_instance_create()_ or false if it was in the system
+before that.
+
+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] 20+ messages in thread* Re: [PATCH 5/9] libtracefs man pages: APIs for managing trace instances.
2020-12-17 9:46 ` [PATCH 5/9] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
@ 2020-12-18 20:08 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 20:08 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:22 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> 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 | 104 ++++++++++++++++++
> 1 file changed, 104 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..ca08269
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-manage.txt
> @@ -0,0 +1,104 @@
> +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.
We should add a description of what a trace instance is:
"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 creates a new trace instance with given
> +_name_, if it does not already exist in the system. It allocates and initializes
> +a new tracefs_instance structure and returns it.
The above description is a little ambiguous to what happen if the instance
already exists in the system. Perhaps reword the above to:
"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()_ destroys the trace _instance_ and frees the
> +tracefs_instance structure.
"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 destroying the trace instance.
> +
> +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.
"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()_.
-- Steve
> +
> +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 instance is
> +created by _tracefs_instance_create()_ or false if it was in the system
> +before that.
> +
> +
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 6/9] libtracefs man pages: APIs for working with files in trace instances.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (4 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 5/9] libtracefs man pages: APIs for managing trace instances Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 20:27 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 7/9] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
` (2 subsequent siblings)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 157 +++++++++++++++++++
1 file changed, 157 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..f1e9707
--- /dev/null
+++ b/Documentation/libtracefs-instances-files.txt
@@ -0,0 +1,157 @@
+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.
+All they have _instance_ argument, to limit the scope on the given trace _instance_ only.
+If _instance_ is NULL, the scope is limited to the main trace instance.
+
+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_.
+
+The _tracefs_instance_get_dir()_ function returns the full path of the directory with
+given _name_ in _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 they do 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] 20+ messages in thread* Re: [PATCH 6/9] libtracefs man pages: APIs for working with files in trace instances.
2020-12-17 9:46 ` [PATCH 6/9] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
@ 2020-12-18 20:27 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 20:27 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:23 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> 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 | 157 +++++++++++++++++++
> 1 file changed, 157 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..f1e9707
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-files.txt
> @@ -0,0 +1,157 @@
> +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.
> +All they have _instance_ argument, to limit the scope on the given trace _instance_ only.
> +If _instance_ is NULL, the scope is limited to the main trace instance.
Replace the above with:
"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_.
Should add: "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 they do not exist.
"or false if it does not exist."
The "it" references the file or directory, not the functions, and "the"
makes it singular.
-- Steve
> +
> +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().
> +
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 7/9] libtracefs man pages: helper APIs for working with trace instances.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (5 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 6/9] libtracefs man pages: APIs for working with files in " Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-18 23:33 ` Steven Rostedt
2020-12-17 9:46 ` [PATCH 8/9] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
2020-12-17 9:46 ` [PATCH 9/9] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
8 siblings, 1 reply; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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 | 111 +++++++++++++++++++
1 file changed, 111 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..1630d5c
--- /dev/null
+++ b/Documentation/libtracefs-instances-utils.txt
@@ -0,0 +1,111 @@
+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.
+
+The _tracefs_instance_exists()_ function checks if an instance with given _name_
+exists in the system.
+
+RETURN VALUE
+------------
+The _tracefs_instance_get_name()_ returns 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 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] 20+ messages in thread* Re: [PATCH 7/9] libtracefs man pages: helper APIs for working with trace instances.
2020-12-17 9:46 ` [PATCH 7/9] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
@ 2020-12-18 23:33 ` Steven Rostedt
0 siblings, 0 replies; 20+ messages in thread
From: Steven Rostedt @ 2020-12-18 23:33 UTC (permalink / raw)
To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel
On Thu, 17 Dec 2020 11:46:24 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
> 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 | 111 +++++++++++++++++++
> 1 file changed, 111 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..1630d5c
> --- /dev/null
> +++ b/Documentation/libtracefs-instances-utils.txt
> @@ -0,0 +1,111 @@
> +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.
Does this include the top level instance? If not, this should be specified.
> +
> +The _tracefs_instance_exists()_ function checks if an instance with given _name_
"with the given _name_"
> +exists in the system.
> +
> +RETURN VALUE
> +------------
> +The _tracefs_instance_get_name()_ returns string or NULL in case of the top
"returns a string or "
> +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 given name
"with the given name"
-- Steve
> +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
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 8/9] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (6 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 7/9] libtracefs man pages: helper APIs for working with " Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
2020-12-17 9:46 ` [PATCH 9/9] libtracefs man pages: helper APIs for working with trace file system Tzvetomir Stoyanov (VMware)
8 siblings, 0 replies; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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] 20+ messages in thread* [PATCH 9/9] libtracefs man pages: helper APIs for working with trace file system.
2020-12-17 9:46 [PATCH 0/9] libtracefs man pages Tzvetomir Stoyanov (VMware)
` (7 preceding siblings ...)
2020-12-17 9:46 ` [PATCH 8/9] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system Tzvetomir Stoyanov (VMware)
@ 2020-12-17 9:46 ` Tzvetomir Stoyanov (VMware)
8 siblings, 0 replies; 20+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-17 9:46 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] 20+ messages in thread