Linux-Trace-Devel Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH 0/6] libtracecmd man pages.
@ 2020-12-23  4:34 Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 1/6] trace-cmd: " Tzvetomir Stoyanov (VMware)
                   ` (5 more replies)
  0 siblings, 6 replies; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Initial implementation of libtracecmd man pages.

Tzvetomir Stoyanov (VMware) (6):
  trace-cmd: libtracecmd man pages
  trace-cmd: Update the RESOURCES section of the trace-cmd man pages
  trace-cmd library man pages: Read recorded events from a trace file.
  trace-cmd library man pages: Open and close trace file.
  trace-cmd library man pages: Manage trace session with multiple trace
    peers.
  trace-cmd library man pages: Read tracing instances from a trace file.

 Documentation/Makefile                        |  97 ++---------
 Documentation/libtracecmd/Makefile            |  34 ++++
 .../libtracecmd/libtracecmd-files.3.txt       |  92 +++++++++++
 .../libtracecmd/libtracecmd-instances.3.txt   | 129 +++++++++++++++
 .../libtracecmd/libtracecmd-peer.3.txt        | 149 +++++++++++++++++
 .../libtracecmd/libtracecmd-record.3.txt      | 152 ++++++++++++++++++
 Documentation/libtracecmd/libtracecmd.3.txt   |  83 ++++++++++
 Documentation/trace-cmd/Makefile              |  44 +++++
 .../trace-cmd-check-events.1.txt              |   2 +-
 .../{ => trace-cmd}/trace-cmd-clear.1.txt     |   2 +-
 .../{ => trace-cmd}/trace-cmd-dump.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-extract.1.txt   |   2 +-
 .../{ => trace-cmd}/trace-cmd-hist.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-list.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-listen.1.txt    |   2 +-
 .../{ => trace-cmd}/trace-cmd-mem.1.txt       |   2 +-
 .../{ => trace-cmd}/trace-cmd-options.1.txt   |   2 +-
 .../{ => trace-cmd}/trace-cmd-profile.1.txt   |   2 +-
 .../{ => trace-cmd}/trace-cmd-record.1.txt    |   2 +-
 .../{ => trace-cmd}/trace-cmd-report.1.txt    |   2 +-
 .../{ => trace-cmd}/trace-cmd-reset.1.txt     |   2 +-
 .../{ => trace-cmd}/trace-cmd-restore.1.txt   |   2 +-
 .../{ => trace-cmd}/trace-cmd-set.1.txt       |   2 +-
 .../{ => trace-cmd}/trace-cmd-show.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-snapshot.1.txt  |   2 +-
 .../{ => trace-cmd}/trace-cmd-split.1.txt     |   2 +-
 .../{ => trace-cmd}/trace-cmd-stack.1.txt     |   2 +-
 .../{ => trace-cmd}/trace-cmd-start.1.txt     |   2 +-
 .../{ => trace-cmd}/trace-cmd-stat.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-stop.1.txt      |   2 +-
 .../{ => trace-cmd}/trace-cmd-stream.1.txt    |   2 +-
 Documentation/{ => trace-cmd}/trace-cmd.1.txt |   2 +-
 .../{ => trace-cmd}/trace-cmd.dat.5.txt       |   2 +-
 scripts/utils.mk                              |  42 +++++
 34 files changed, 761 insertions(+), 111 deletions(-)
 create mode 100644 Documentation/libtracecmd/Makefile
 create mode 100644 Documentation/libtracecmd/libtracecmd-files.3.txt
 create mode 100644 Documentation/libtracecmd/libtracecmd-instances.3.txt
 create mode 100644 Documentation/libtracecmd/libtracecmd-peer.3.txt
 create mode 100644 Documentation/libtracecmd/libtracecmd-record.3.txt
 create mode 100644 Documentation/libtracecmd/libtracecmd.3.txt
 create mode 100644 Documentation/trace-cmd/Makefile
 rename Documentation/{ => trace-cmd}/trace-cmd-check-events.1.txt (94%)
 rename Documentation/{ => trace-cmd}/trace-cmd-clear.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd-dump.1.txt (98%)
 rename Documentation/{ => trace-cmd}/trace-cmd-extract.1.txt (97%)
 rename Documentation/{ => trace-cmd}/trace-cmd-hist.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd-list.1.txt (97%)
 rename Documentation/{ => trace-cmd}/trace-cmd-listen.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd-mem.1.txt (98%)
 rename Documentation/{ => trace-cmd}/trace-cmd-options.1.txt (91%)
 rename Documentation/{ => trace-cmd}/trace-cmd-profile.1.txt (99%)
 rename Documentation/{ => trace-cmd}/trace-cmd-record.1.txt (99%)
 rename Documentation/{ => trace-cmd}/trace-cmd-report.1.txt (99%)
 rename Documentation/{ => trace-cmd}/trace-cmd-reset.1.txt (98%)
 rename Documentation/{ => trace-cmd}/trace-cmd-restore.1.txt (98%)
 rename Documentation/{ => trace-cmd}/trace-cmd-set.1.txt (99%)
 rename Documentation/{ => trace-cmd}/trace-cmd-show.1.txt (97%)
 rename Documentation/{ => trace-cmd}/trace-cmd-snapshot.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd-split.1.txt (97%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stack.1.txt (94%)
 rename Documentation/{ => trace-cmd}/trace-cmd-start.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stat.1.txt (96%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stop.1.txt (96%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stream.1.txt (95%)
 rename Documentation/{ => trace-cmd}/trace-cmd.1.txt (97%)
 rename Documentation/{ => trace-cmd}/trace-cmd.dat.5.txt (99%)

-- 
2.28.0


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

* [PATCH 1/6] trace-cmd: libtracecmd man pages
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 2/6] trace-cmd: Update the RESOURCES section of the trace-cmd " Tzvetomir Stoyanov (VMware)
                   ` (4 subsequent siblings)
  5 siblings, 0 replies; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Initial implementation of trace-cmd library man pages.
trace-cmd/Documentation directory is reorganized to hold both trace-cmd
application and library man pages, each in its own subdirectory. The
first libtracecmd man page is implemented: "man libtracecmd" with a list
of all library APIs.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/Makefile                        | 97 +++----------------
 Documentation/libtracecmd/Makefile            | 34 +++++++
 Documentation/libtracecmd/libtracecmd.3.txt   | 83 ++++++++++++++++
 Documentation/trace-cmd/Makefile              | 44 +++++++++
 .../trace-cmd-check-events.1.txt              |  0
 .../{ => trace-cmd}/trace-cmd-clear.1.txt     |  0
 .../{ => trace-cmd}/trace-cmd-dump.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-extract.1.txt   |  0
 .../{ => trace-cmd}/trace-cmd-hist.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-list.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-listen.1.txt    |  0
 .../{ => trace-cmd}/trace-cmd-mem.1.txt       |  0
 .../{ => trace-cmd}/trace-cmd-options.1.txt   |  0
 .../{ => trace-cmd}/trace-cmd-profile.1.txt   |  0
 .../{ => trace-cmd}/trace-cmd-record.1.txt    |  0
 .../{ => trace-cmd}/trace-cmd-report.1.txt    |  0
 .../{ => trace-cmd}/trace-cmd-reset.1.txt     |  0
 .../{ => trace-cmd}/trace-cmd-restore.1.txt   |  0
 .../{ => trace-cmd}/trace-cmd-set.1.txt       |  0
 .../{ => trace-cmd}/trace-cmd-show.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-snapshot.1.txt  |  0
 .../{ => trace-cmd}/trace-cmd-split.1.txt     |  0
 .../{ => trace-cmd}/trace-cmd-stack.1.txt     |  0
 .../{ => trace-cmd}/trace-cmd-start.1.txt     |  0
 .../{ => trace-cmd}/trace-cmd-stat.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-stop.1.txt      |  0
 .../{ => trace-cmd}/trace-cmd-stream.1.txt    |  0
 Documentation/{ => trace-cmd}/trace-cmd.1.txt |  0
 .../{ => trace-cmd}/trace-cmd.dat.5.txt       |  0
 scripts/utils.mk                              | 42 ++++++++
 30 files changed, 214 insertions(+), 86 deletions(-)
 create mode 100644 Documentation/libtracecmd/Makefile
 create mode 100644 Documentation/libtracecmd/libtracecmd.3.txt
 create mode 100644 Documentation/trace-cmd/Makefile
 rename Documentation/{ => trace-cmd}/trace-cmd-check-events.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-clear.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-dump.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-extract.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-hist.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-list.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-listen.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-mem.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-options.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-profile.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-record.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-report.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-reset.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-restore.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-set.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-show.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-snapshot.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-split.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stack.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-start.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stat.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stop.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd-stream.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd.1.txt (100%)
 rename Documentation/{ => trace-cmd}/trace-cmd.dat.5.txt (100%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f2c32640..8e979ece 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,48 +1,5 @@
+# SPDX-License-Identifier: GPL-2.0
 
-obj := $(obj)/Documentation
-src := $(src)/Documentation
-
-ifeq ($(VERBOSE),1)
-  Q =
-  print_asciidoc =
-  print_xsltproc =
-  print_install =
-  hide_xsltproc_output =
-else
-  Q = @
-  print_asciidoc =		echo '      ASCIIDOC            '`basename $@`;
-  print_xsltproc =		echo '      XSLTPROC            '`basename $@`;
-  print_install =		echo '      INSTALL             '`basename $1`'	to	$(DESTDIR_SQ)'$2;
-  hide_xsltproc_output = 2> /dev/null
-endif
-
-define manpage.xsl
-	if [ -z ${MANPAGE_DOCBOOK_XSL} ]; then 			\
-		echo "*********************************";	\
-		echo "** No docbook.xsl is installed **";	\
-		echo "** Can't make man pages        **";	\
-		echo "*********************************";	\
-		exit 1;						\
-	fi
-endef
-
-do_asciidoc_build =				\
-	($(print_asciidoc)			\
-	 asciidoc -d manpage -b docbook -o $@ $<)
-
-do_xsltproc_build =				\
-	($(print_xsltproc)			\
-	 xsltproc --nonet -o $@ ${MANPAGE_DOCBOOK_XSL} $< $(hide_xsltproc_output))
-
-#
-# asciidoc requires a synopsis, but file format man pages (5) do
-# not require them. This removes it from the file in the final step.
-define remove_synopsis
-	(sed -e '/^\.SH "SYNOPSIS"/,/ignore/d' $1 > $1.tmp;\
-	 mv $1.tmp $1)
-endef
-
-#
 # Most likely a docbook.xsl is already installed on the users system
 # instead of creating a new wheel, lets reuse what's already there.
 #
@@ -50,51 +7,19 @@ FIND_MANPAGE_DOCBOOK_XSL :=  $(shell find /usr -name docbook.xsl 2>/dev/null | g
 
 MANPAGE_DOCBOOK_XSL ?= ${FIND_MANPAGE_DOCBOOK_XSL}
 
-$(obj)/%.xsl: $(src)/%.txt
-	$(Q)mkdir -p $(obj)
-	$(Q)$(do_asciidoc_build)
-
-
-$(obj)/%.1: $(obj)/%.1.xsl
-	@$(call manpage.xsl)
-	$(Q)$(do_xsltproc_build)
-
-$(obj)/%.5: $(obj)/%.5.xsl
-	@$(call manpage.xsl)
-	$(Q)$(do_xsltproc_build)
-	$(Q)$(call remove_synopsis, $@)
-
-TEXT1 = $(wildcard *.1.txt)
-MAN1 = $(patsubst %.1.txt,$(obj)/%.1, ${TEXT1})
-TEXT5 = $(wildcard *.5.txt)
-MAN5 = $(patsubst %.5.txt,$(obj)/%.5, ${TEXT5})
-
-all: $(MAN1) $(MAN5)
-
-# Need to find out how to export a macro instead of
-# copying this from the main Makefile.
-define do_install_data
-	$(print_install)				\
-	if [ ! -d '$(DESTDIR_SQ)$2' ]; then		\
-		$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$2';	\
-	fi;						\
-	$(INSTALL) -m 644 $1 '$(DESTDIR_SQ)$2'
-endef
+doc_dir:=$(src)/Documentation
 
+export MANPAGE_DOCBOOK_XSL doc_dir
 
-MAN1_INSTALL = $(MAN1:%.1=%.1.install)
-MAN5_INSTALL = $(MAN5:%.5=%.5.install)
+SUBDIR += trace-cmd
+SUBDIR += libtracecmd
 
-$(MAN1_INSTALL): %.1.install : %.1 force
-	$(Q)$(call do_install_data,$<,$(man_dir_SQ)/man1)
-$(MAN5_INSTALL): %.5.install : %.5 force
-	$(Q)$(call do_install_data,$<,$(man_dir_SQ)/man5)
+.PHONY: $(SUBDIR)
 
-install: $(MAN1_INSTALL) $(MAN5_INSTALL)
+all: $(SUBDIR)
+clean: $(SUBDIR)
+install: $(SUBDIR)
 
-clean:
-	(cd $(obj); \
-	 $(RM) *.xml *.xsl *.1 *.5)
+$(SUBDIR):
+	make -C $@ $(MAKECMDGOALS)
 
-.PHONE: force
-force:
diff --git a/Documentation/libtracecmd/Makefile b/Documentation/libtracecmd/Makefile
new file mode 100644
index 00000000..196cac7c
--- /dev/null
+++ b/Documentation/libtracecmd/Makefile
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GPL-2.0
+
+# Include the utils
+include $(src)/scripts/utils.mk
+
+bdir:=$(doc_dir)/libtracecmd
+
+$(bdir)/%.xsl: $(bdir)/%.txt
+	$(Q)mkdir -p $(bdir)
+	$(Q)$(do_asciidoc_build)
+
+
+$(bdir)/%.3: $(bdir)/%.3.xsl
+	@$(call manpage.xsl)
+	$(Q)$(do_xsltproc_build)
+
+TEXT3 = $(wildcard $(bdir)/*.3.txt)
+MAN3 = $(patsubst $(bdir)/%.3.txt,$(bdir)/%.3, ${TEXT3})
+
+all: $(MAN3)
+
+MAN3_INSTALL = $(MAN3:%.3=%.3.install)
+
+$(MAN3_INSTALL): %.3.install : %.3 force
+	$(Q)$(call do_install_docs,$<,$(man_dir_SQ)/man3)
+
+install: $(MAN3_INSTALL)
+
+clean:
+	$(Q)(cd $(bdir); \
+		$(RM) *.xml *.xsl *.3)
+
+.PHONE: force
+force:
diff --git a/Documentation/libtracecmd/libtracecmd.3.txt b/Documentation/libtracecmd/libtracecmd.3.txt
new file mode 100644
index 00000000..f080b04d
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd.3.txt
@@ -0,0 +1,83 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+libtracecmd - trace-cmd library APIs
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+Open and close trace file:
+	struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_);
+	void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
+
+Read tracing records from a trace file:
+	int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
+	struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
+	struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
+	struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_);
+	void *tracecmd_free_record*(struct tep_record pass:[*]_record_);
+	struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_handle_);
+
+Read tracing instances from a trace file:
+	int *tracecmd_buffer_instances*(struct tracecmd_input pass:[*]_handle_);
+	const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_);
+	struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_);
+
+Get traceing peer information from a trace file:
+	int *tracecmd_pair_peer*(struct tracecmd_input pass:[*]_handle_, struct tracecmd_input pass:[*]_peer_);
+	void tracecmd_unpair_peer(struct tracecmd_input pass:[*]handle);
+	unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_);
+	int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_);
+--
+
+DESCRIPTION
+-----------
+The libtracecmd(3) library provides APIs to read, parse and write
+_trace-cmd.dat(5)_ files, recorded with _trace-cmd(1)_ application and containing
+tracing information from ftrace, the official Linux kernel tracer.
+
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-libtracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_
+_libtracefs(3)_
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+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
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
diff --git a/Documentation/trace-cmd/Makefile b/Documentation/trace-cmd/Makefile
new file mode 100644
index 00000000..3f28d39c
--- /dev/null
+++ b/Documentation/trace-cmd/Makefile
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-2.0
+
+# Include the utils
+include $(src)/scripts/utils.mk
+
+bdir:=$(doc_dir)/trace-cmd
+
+$(bdir)/%.xsl: $(bdir)/%.txt
+	$(Q)mkdir -p $(bdir)
+	$(Q)$(do_asciidoc_build)
+
+
+$(bdir)/%.1: $(bdir)/%.1.xsl
+	@$(call manpage.xsl)
+	$(Q)$(do_xsltproc_build)
+
+$(bdir)/%.5: $(bdir)/%.5.xsl
+	@$(call manpage.xsl)
+	$(Q)$(do_xsltproc_build)
+	$(Q)$(call remove_synopsis, $@)
+
+ TEXT1 = $(wildcard $(bdir)/*.1.txt)
+ MAN1 = $(patsubst $(bdir)/%.1.txt,$(bdir)/%.1, ${TEXT1})
+ TEXT5 = $(wildcard $(bdir)/*.5.txt)
+ MAN5 = $(patsubst $(bdir)/%.5.txt,$(bdir)/%.5, ${TEXT5})
+
+all: $(MAN1) $(MAN5)
+
+MAN1_INSTALL = $(MAN1:%.1=%.1.install)
+MAN5_INSTALL = $(MAN5:%.5=%.5.install)
+
+$(MAN1_INSTALL): %.1.install : %.1 force
+	$(Q)$(call do_install_docs,$<,$(man_dir_SQ)/man1)
+$(MAN5_INSTALL): %.5.install : %.5 force
+	$(Q)$(call do_install_docs,$<,$(man_dir_SQ)/man5)
+
+install: $(MAN1_INSTALL) $(MAN5_INSTALL)
+
+clean:
+	$(Q)(cd $(bdir); \
+		$(RM) *.xml *.xsl *.1 *.5)
+
+.PHONE: force
+force:
diff --git a/Documentation/trace-cmd-check-events.1.txt b/Documentation/trace-cmd/trace-cmd-check-events.1.txt
similarity index 100%
rename from Documentation/trace-cmd-check-events.1.txt
rename to Documentation/trace-cmd/trace-cmd-check-events.1.txt
diff --git a/Documentation/trace-cmd-clear.1.txt b/Documentation/trace-cmd/trace-cmd-clear.1.txt
similarity index 100%
rename from Documentation/trace-cmd-clear.1.txt
rename to Documentation/trace-cmd/trace-cmd-clear.1.txt
diff --git a/Documentation/trace-cmd-dump.1.txt b/Documentation/trace-cmd/trace-cmd-dump.1.txt
similarity index 100%
rename from Documentation/trace-cmd-dump.1.txt
rename to Documentation/trace-cmd/trace-cmd-dump.1.txt
diff --git a/Documentation/trace-cmd-extract.1.txt b/Documentation/trace-cmd/trace-cmd-extract.1.txt
similarity index 100%
rename from Documentation/trace-cmd-extract.1.txt
rename to Documentation/trace-cmd/trace-cmd-extract.1.txt
diff --git a/Documentation/trace-cmd-hist.1.txt b/Documentation/trace-cmd/trace-cmd-hist.1.txt
similarity index 100%
rename from Documentation/trace-cmd-hist.1.txt
rename to Documentation/trace-cmd/trace-cmd-hist.1.txt
diff --git a/Documentation/trace-cmd-list.1.txt b/Documentation/trace-cmd/trace-cmd-list.1.txt
similarity index 100%
rename from Documentation/trace-cmd-list.1.txt
rename to Documentation/trace-cmd/trace-cmd-list.1.txt
diff --git a/Documentation/trace-cmd-listen.1.txt b/Documentation/trace-cmd/trace-cmd-listen.1.txt
similarity index 100%
rename from Documentation/trace-cmd-listen.1.txt
rename to Documentation/trace-cmd/trace-cmd-listen.1.txt
diff --git a/Documentation/trace-cmd-mem.1.txt b/Documentation/trace-cmd/trace-cmd-mem.1.txt
similarity index 100%
rename from Documentation/trace-cmd-mem.1.txt
rename to Documentation/trace-cmd/trace-cmd-mem.1.txt
diff --git a/Documentation/trace-cmd-options.1.txt b/Documentation/trace-cmd/trace-cmd-options.1.txt
similarity index 100%
rename from Documentation/trace-cmd-options.1.txt
rename to Documentation/trace-cmd/trace-cmd-options.1.txt
diff --git a/Documentation/trace-cmd-profile.1.txt b/Documentation/trace-cmd/trace-cmd-profile.1.txt
similarity index 100%
rename from Documentation/trace-cmd-profile.1.txt
rename to Documentation/trace-cmd/trace-cmd-profile.1.txt
diff --git a/Documentation/trace-cmd-record.1.txt b/Documentation/trace-cmd/trace-cmd-record.1.txt
similarity index 100%
rename from Documentation/trace-cmd-record.1.txt
rename to Documentation/trace-cmd/trace-cmd-record.1.txt
diff --git a/Documentation/trace-cmd-report.1.txt b/Documentation/trace-cmd/trace-cmd-report.1.txt
similarity index 100%
rename from Documentation/trace-cmd-report.1.txt
rename to Documentation/trace-cmd/trace-cmd-report.1.txt
diff --git a/Documentation/trace-cmd-reset.1.txt b/Documentation/trace-cmd/trace-cmd-reset.1.txt
similarity index 100%
rename from Documentation/trace-cmd-reset.1.txt
rename to Documentation/trace-cmd/trace-cmd-reset.1.txt
diff --git a/Documentation/trace-cmd-restore.1.txt b/Documentation/trace-cmd/trace-cmd-restore.1.txt
similarity index 100%
rename from Documentation/trace-cmd-restore.1.txt
rename to Documentation/trace-cmd/trace-cmd-restore.1.txt
diff --git a/Documentation/trace-cmd-set.1.txt b/Documentation/trace-cmd/trace-cmd-set.1.txt
similarity index 100%
rename from Documentation/trace-cmd-set.1.txt
rename to Documentation/trace-cmd/trace-cmd-set.1.txt
diff --git a/Documentation/trace-cmd-show.1.txt b/Documentation/trace-cmd/trace-cmd-show.1.txt
similarity index 100%
rename from Documentation/trace-cmd-show.1.txt
rename to Documentation/trace-cmd/trace-cmd-show.1.txt
diff --git a/Documentation/trace-cmd-snapshot.1.txt b/Documentation/trace-cmd/trace-cmd-snapshot.1.txt
similarity index 100%
rename from Documentation/trace-cmd-snapshot.1.txt
rename to Documentation/trace-cmd/trace-cmd-snapshot.1.txt
diff --git a/Documentation/trace-cmd-split.1.txt b/Documentation/trace-cmd/trace-cmd-split.1.txt
similarity index 100%
rename from Documentation/trace-cmd-split.1.txt
rename to Documentation/trace-cmd/trace-cmd-split.1.txt
diff --git a/Documentation/trace-cmd-stack.1.txt b/Documentation/trace-cmd/trace-cmd-stack.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stack.1.txt
rename to Documentation/trace-cmd/trace-cmd-stack.1.txt
diff --git a/Documentation/trace-cmd-start.1.txt b/Documentation/trace-cmd/trace-cmd-start.1.txt
similarity index 100%
rename from Documentation/trace-cmd-start.1.txt
rename to Documentation/trace-cmd/trace-cmd-start.1.txt
diff --git a/Documentation/trace-cmd-stat.1.txt b/Documentation/trace-cmd/trace-cmd-stat.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stat.1.txt
rename to Documentation/trace-cmd/trace-cmd-stat.1.txt
diff --git a/Documentation/trace-cmd-stop.1.txt b/Documentation/trace-cmd/trace-cmd-stop.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stop.1.txt
rename to Documentation/trace-cmd/trace-cmd-stop.1.txt
diff --git a/Documentation/trace-cmd-stream.1.txt b/Documentation/trace-cmd/trace-cmd-stream.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stream.1.txt
rename to Documentation/trace-cmd/trace-cmd-stream.1.txt
diff --git a/Documentation/trace-cmd.1.txt b/Documentation/trace-cmd/trace-cmd.1.txt
similarity index 100%
rename from Documentation/trace-cmd.1.txt
rename to Documentation/trace-cmd/trace-cmd.1.txt
diff --git a/Documentation/trace-cmd.dat.5.txt b/Documentation/trace-cmd/trace-cmd.dat.5.txt
similarity index 100%
rename from Documentation/trace-cmd.dat.5.txt
rename to Documentation/trace-cmd/trace-cmd.dat.5.txt
diff --git a/scripts/utils.mk b/scripts/utils.mk
index 03389126..3425d4e8 100644
--- a/scripts/utils.mk
+++ b/scripts/utils.mk
@@ -32,6 +32,10 @@ ifeq ($(findstring 1,$(SILENT)$(VERBOSE)),1)
   print_install =
   print_uninstall =
   print_update =
+  print_asciidoc =
+  print_xsltproc =
+  print_install =
+  hide_xsltproc_output =
 else
   print_compile =		echo '  $(GUI)COMPILE            '$(GOBJ);
   print_app_build =		echo '  $(GUI)BUILD              '$(GOBJ);
@@ -43,6 +47,10 @@ else
   print_install =		echo '  $(GUI)INSTALL     '$(GSPACE)$1'	to	$(DESTDIR_SQ)$2';
   print_update =		echo '  $(GUI)UPDATE             '$(GOBJ);
   print_uninstall =		echo '  $(GUI)UNINSTALLING $(DESTDIR_SQ)$1';
+  print_asciidoc =		echo '  ASCIIDOC            '`basename $@`;
+  print_xsltproc =		echo '  XSLTPROC            '`basename $@`;
+  print_install =		echo '  INSTALL             '`basename $1`'	to	$(DESTDIR_SQ)'$2;
+  hide_xsltproc_output = 2> /dev/null
 endif
 
 do_fpic_compile =					\
@@ -163,3 +171,37 @@ define do_make_pkgconfig_file
 	sed -i "s|LIB_DIR|$(libdir)|g" ${PKG_CONFIG_FILE}; \
 	sed -i "s|HEADER_DIR|$(includedir)/trace-cmd|g" ${PKG_CONFIG_FILE};
 endef
+
+define manpage.xsl
+	if [ -z ${MANPAGE_DOCBOOK_XSL} ]; then 			\
+		echo "*********************************";	\
+		echo "** No docbook.xsl is installed **";	\
+		echo "** Can't make man pages        **";	\
+		echo "*********************************";	\
+		exit 1;						\
+	fi
+endef
+
+do_asciidoc_build =				\
+	($(print_asciidoc)			\
+	 asciidoc -d manpage -b docbook -o $@ $<)
+
+do_xsltproc_build =				\
+	($(print_xsltproc)			\
+	 xsltproc --nonet -o $@ ${MANPAGE_DOCBOOK_XSL} $< $(hide_xsltproc_output))
+
+#
+# asciidoc requires a synopsis, but file format man pages (5) do
+# not require them. This removes it from the file in the final step.
+define remove_synopsis
+	(sed -e '/^\.SH "SYNOPSIS"/,/ignore/d' $1 > $1.tmp;\
+	 mv $1.tmp $1)
+endef
+
+define do_install_docs
+	$(print_install)				\
+	if [ ! -d '$(DESTDIR_SQ)$2' ]; then		\
+		$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$2';	\
+	fi;						\
+	$(INSTALL) -m 644 $1 '$(DESTDIR_SQ)$2'
+endef
-- 
2.28.0


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

* [PATCH 2/6] trace-cmd: Update the RESOURCES section of the trace-cmd man pages
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 1/6] trace-cmd: " Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file Tzvetomir Stoyanov (VMware)
                   ` (3 subsequent siblings)
  5 siblings, 0 replies; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

trace-cmd has a new official repository, the RESOURCES
section of the man pages should point to it. Updated with
https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 Documentation/trace-cmd/trace-cmd-check-events.1.txt | 2 +-
 Documentation/trace-cmd/trace-cmd-clear.1.txt        | 2 +-
 Documentation/trace-cmd/trace-cmd-dump.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-extract.1.txt      | 2 +-
 Documentation/trace-cmd/trace-cmd-hist.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-list.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-listen.1.txt       | 2 +-
 Documentation/trace-cmd/trace-cmd-mem.1.txt          | 2 +-
 Documentation/trace-cmd/trace-cmd-options.1.txt      | 2 +-
 Documentation/trace-cmd/trace-cmd-profile.1.txt      | 2 +-
 Documentation/trace-cmd/trace-cmd-record.1.txt       | 2 +-
 Documentation/trace-cmd/trace-cmd-report.1.txt       | 2 +-
 Documentation/trace-cmd/trace-cmd-reset.1.txt        | 2 +-
 Documentation/trace-cmd/trace-cmd-restore.1.txt      | 2 +-
 Documentation/trace-cmd/trace-cmd-set.1.txt          | 2 +-
 Documentation/trace-cmd/trace-cmd-show.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-snapshot.1.txt     | 2 +-
 Documentation/trace-cmd/trace-cmd-split.1.txt        | 2 +-
 Documentation/trace-cmd/trace-cmd-stack.1.txt        | 2 +-
 Documentation/trace-cmd/trace-cmd-start.1.txt        | 2 +-
 Documentation/trace-cmd/trace-cmd-stat.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-stop.1.txt         | 2 +-
 Documentation/trace-cmd/trace-cmd-stream.1.txt       | 2 +-
 Documentation/trace-cmd/trace-cmd.1.txt              | 2 +-
 Documentation/trace-cmd/trace-cmd.dat.5.txt          | 2 +-
 25 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/trace-cmd/trace-cmd-check-events.1.txt b/Documentation/trace-cmd/trace-cmd-check-events.1.txt
index 73ec1a8b..c98ff3c6 100644
--- a/Documentation/trace-cmd/trace-cmd-check-events.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-check-events.1.txt
@@ -36,7 +36,7 @@ Written by Vaibhav Nagarnaik, <vnagarnaik@google.com>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-clear.1.txt b/Documentation/trace-cmd/trace-cmd-clear.1.txt
index a0ae36e9..74236960 100644
--- a/Documentation/trace-cmd/trace-cmd-clear.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-clear.1.txt
@@ -48,4 +48,4 @@ GNU Public License (GPL).
 
 RESOURCES
 ---------
-https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git
\ No newline at end of file
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
\ No newline at end of file
diff --git a/Documentation/trace-cmd/trace-cmd-dump.1.txt b/Documentation/trace-cmd/trace-cmd-dump.1.txt
index e29bfe86..71b8e655 100644
--- a/Documentation/trace-cmd/trace-cmd-dump.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-dump.1.txt
@@ -123,7 +123,7 @@ AUTHOR
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-extract.1.txt b/Documentation/trace-cmd/trace-cmd-extract.1.txt
index 917a6371..4444733d 100644
--- a/Documentation/trace-cmd/trace-cmd-extract.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-extract.1.txt
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-hist.1.txt b/Documentation/trace-cmd/trace-cmd-hist.1.txt
index b17936d0..169f8d7b 100644
--- a/Documentation/trace-cmd/trace-cmd-hist.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-hist.1.txt
@@ -41,7 +41,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-list.1.txt b/Documentation/trace-cmd/trace-cmd-list.1.txt
index bba45ea4..0ad62643 100644
--- a/Documentation/trace-cmd/trace-cmd-list.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-list.1.txt
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-listen.1.txt b/Documentation/trace-cmd/trace-cmd-listen.1.txt
index a242c49e..8697328c 100644
--- a/Documentation/trace-cmd/trace-cmd-listen.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-listen.1.txt
@@ -49,7 +49,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-mem.1.txt b/Documentation/trace-cmd/trace-cmd-mem.1.txt
index 9e811b91..90e430b8 100644
--- a/Documentation/trace-cmd/trace-cmd-mem.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-mem.1.txt
@@ -65,7 +65,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-options.1.txt b/Documentation/trace-cmd/trace-cmd-options.1.txt
index e7faf320..bcdf0533 100644
--- a/Documentation/trace-cmd/trace-cmd-options.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-options.1.txt
@@ -26,7 +26,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-profile.1.txt b/Documentation/trace-cmd/trace-cmd-profile.1.txt
index 3ffce86b..0d1dd8e8 100644
--- a/Documentation/trace-cmd/trace-cmd-profile.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-profile.1.txt
@@ -667,7 +667,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-record.1.txt b/Documentation/trace-cmd/trace-cmd-record.1.txt
index 99d1a156..643659ad 100644
--- a/Documentation/trace-cmd/trace-cmd-record.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-record.1.txt
@@ -461,7 +461,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-report.1.txt b/Documentation/trace-cmd/trace-cmd-report.1.txt
index de616cf4..766c9a57 100644
--- a/Documentation/trace-cmd/trace-cmd-report.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-report.1.txt
@@ -487,7 +487,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-reset.1.txt b/Documentation/trace-cmd/trace-cmd-reset.1.txt
index bff45300..eee86751 100644
--- a/Documentation/trace-cmd/trace-cmd-reset.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-reset.1.txt
@@ -107,7 +107,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-restore.1.txt b/Documentation/trace-cmd/trace-cmd-restore.1.txt
index 290b0acd..ebcbb1b6 100644
--- a/Documentation/trace-cmd/trace-cmd-restore.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-restore.1.txt
@@ -96,7 +96,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-set.1.txt b/Documentation/trace-cmd/trace-cmd-set.1.txt
index 2f95e07f..931d3abd 100644
--- a/Documentation/trace-cmd/trace-cmd-set.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-set.1.txt
@@ -255,7 +255,7 @@ Written by Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-show.1.txt b/Documentation/trace-cmd/trace-cmd-show.1.txt
index b17851ef..ea2fda28 100644
--- a/Documentation/trace-cmd/trace-cmd-show.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-show.1.txt
@@ -91,7 +91,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-snapshot.1.txt b/Documentation/trace-cmd/trace-cmd-snapshot.1.txt
index 6d94ada0..0a34bcd9 100644
--- a/Documentation/trace-cmd/trace-cmd-snapshot.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-snapshot.1.txt
@@ -56,7 +56,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-split.1.txt b/Documentation/trace-cmd/trace-cmd-split.1.txt
index b8308bbc..25385796 100644
--- a/Documentation/trace-cmd/trace-cmd-split.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-split.1.txt
@@ -98,7 +98,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-stack.1.txt b/Documentation/trace-cmd/trace-cmd-stack.1.txt
index 6b5f0c08..a00c6900 100644
--- a/Documentation/trace-cmd/trace-cmd-stack.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-stack.1.txt
@@ -36,7 +36,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-start.1.txt b/Documentation/trace-cmd/trace-cmd-start.1.txt
index 07f2ed3a..03c5d127 100644
--- a/Documentation/trace-cmd/trace-cmd-start.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-start.1.txt
@@ -42,7 +42,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-stat.1.txt b/Documentation/trace-cmd/trace-cmd-stat.1.txt
index 2f1a9c8b..e5fccce9 100644
--- a/Documentation/trace-cmd/trace-cmd-stat.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-stat.1.txt
@@ -57,7 +57,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-stop.1.txt b/Documentation/trace-cmd/trace-cmd-stop.1.txt
index 1955fa71..313192c3 100644
--- a/Documentation/trace-cmd/trace-cmd-stop.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-stop.1.txt
@@ -54,7 +54,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd-stream.1.txt b/Documentation/trace-cmd/trace-cmd-stream.1.txt
index 10094028..f83652b8 100644
--- a/Documentation/trace-cmd/trace-cmd-stream.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-stream.1.txt
@@ -41,7 +41,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd.1.txt b/Documentation/trace-cmd/trace-cmd.1.txt
index 5548ed27..b330b4fe 100644
--- a/Documentation/trace-cmd/trace-cmd.1.txt
+++ b/Documentation/trace-cmd/trace-cmd.1.txt
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
diff --git a/Documentation/trace-cmd/trace-cmd.dat.5.txt b/Documentation/trace-cmd/trace-cmd.dat.5.txt
index d849439b..8d285353 100644
--- a/Documentation/trace-cmd/trace-cmd.dat.5.txt
+++ b/Documentation/trace-cmd/trace-cmd.dat.5.txt
@@ -258,7 +258,7 @@ Written by Steven Rostedt, <rostedt@goodmis.org>
 
 RESOURCES
 ---------
-git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
 
 COPYING
 -------
-- 
2.28.0


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

* [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file.
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 1/6] trace-cmd: " Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 2/6] trace-cmd: Update the RESOURCES section of the trace-cmd " Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  2021-01-13 22:18   ` Steven Rostedt
  2020-12-23  4:34 ` [PATCH 4/6] trace-cmd library man pages: Open and close " Tzvetomir Stoyanov (VMware)
                   ` (2 subsequent siblings)
  5 siblings, 1 reply; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
 tracecmd_init_data()
 tracecmd_read_cpu_first()
 tracecmd_read_data()
 tracecmd_read_at()
 tracecmd_free_record()
 tracecmd_get_tep()

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

diff --git a/Documentation/libtracecmd/libtracecmd-record.3.txt b/Documentation/libtracecmd/libtracecmd-record.3.txt
new file mode 100644
index 00000000..194b1670
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd-record.3.txt
@@ -0,0 +1,152 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+tracecmd_init_data, tracecmd_read_cpu_first, tracecmd_read_data
+tracecmd_read_at, tracecmd_free_record, tracecmd_get_tep
+- Read recorded events from a trace file.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
+struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
+struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
+struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_);
+void *tracecmd_free_record*(struct tep_record pass:[*]_record_);
+struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_handle_);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to read tracing data from a trace file opened
+with _tracecmd_open_head()(3)_
+
+The _tracecmd_init_data()_ function initializes the _handle_ for reading
+trace data from the file associated with it. This API must be called before
+any of the _tracecmd_read__ APIs.
+
+The _tracecmd_read_cpu_first()_ function reads the first trace record
+for a given _cpu_ from a trace file associated with _handle_. The returned
+record must be freed with _tracecmd_free_record()_.
+
+The _tracecmd_read_data()_ function reads the next trace record for
+a given _cpu_ from a trace file associated with _handle_ and increments
+the read location pointer, so that the next call to _tracecmd_read_data()_
+will not read the same record again. The returned record must be freed
+with _tracecmd_free_record()_.
+
+The _tracecmd_read_at()_ function reads a trace record from a specific
+_offset_ within the file associated with _handle_. The CPU on which the
+recorded event occurred is stored in the _cpu_. The function does not
+change the current read location pointer. The returned record must be
+freed with _tracecmd_free_record()_.
+
+The _tracecmd_free_record()_ function frees a _record_ returned by any
+of the _tracecmd_read__ APIs.
+
+The _tracecmd_get_tep()_ function returns a tep context for a given
+_handle_.
+
+RETURN VALUE
+------------
+The _tracecmd_init_data()_ function returns -1 in case of an error or
+0 otherwise.
+
+The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and
+_tracecmd_read_at()_ functions return a pointer to struct tep_record or
+NULL in case of an error.The returned record must be freed with
+_tracecmd_free_record()_.
+
+The _tracecmd_get_tep()_ function returns a pointer to tep context or
+NULL if there is no tep context for the given _handle_. The returned
+tep pointer must *not* be freed.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <trace-cmd.h>
+...
+struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+	if (!handle) {
+		/* Failed to open trace.dat file */
+	}
+...
+unsigned long long offset = 0;
+struct tep_record *rec;
+int cpu = 0;
+
+	if (tracecmd_init_data(handle) < 0) {
+		/* Failed to initialize hadle for reading the trace data */
+	}
+
+	rec = tracecmd_read_cpu_first(handle, cpu);
+	while (rec) {
+		...
+		if ( /* some interesting record noticed */) {
+			/* store the offset of the interesting record */
+			offset = rec->offset;
+		}
+		...
+		tracecmd_free_record(rec);
+		rec = tracecmd_read_data(handle, cpu);
+	}
+	...
+	if (offset) {
+		rec = tracecmd_read_at(handle, offset, &cpu);
+		if (rec) {
+			/* Got record at offset on cpu */
+			...
+			tracecmd_free_record(rec);
+		}
+	}
+
+...
+	tracecmd_close(hadle);
+
+--
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-libtracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+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
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
-- 
2.28.0


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

* [PATCH 4/6] trace-cmd library man pages: Open and close trace file.
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
                   ` (2 preceding siblings ...)
  2020-12-23  4:34 ` [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers Tzvetomir Stoyanov (VMware)
  2020-12-23  4:34 ` [PATCH 6/6] trace-cmd library man pages: Read tracing instances from a trace file Tzvetomir Stoyanov (VMware)
  5 siblings, 0 replies; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
 tracecmd_open_head()
 tracecmd_close()

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

diff --git a/Documentation/libtracecmd/libtracecmd-files.3.txt b/Documentation/libtracecmd/libtracecmd-files.3.txt
new file mode 100644
index 00000000..7cf12ea4
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd-files.3.txt
@@ -0,0 +1,92 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+tracecmd_open_head, tracecmd_close - Open and close trace file.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_);
+void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to open and close a trace file recorded by
+_trace-cmd(1)_ and containing tracing information from ftrace, the official
+Linux kernel tracer. The opened file is represented by a _tracecmd_input_
+structure, all other library APIs that work with the file require a pointer
+to the structure.
+
+The _tracecmd_open_head()_ function opens a given trace _file_, parses the
+headers from the file, allocates and initializes _tracecmd_input_ structure
+representing the file.
+
+The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input
+structure, previously allocated with _tracecmd_open_head()_.
+
+RETURN VALUE
+------------
+The _tracecmd_open_head()_ function returns a pointer to tracecmd_input
+structure or NULL in case of an error. The returned structure must be free
+with _tracecmd_close()_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <trace-cmd.h>
+...
+struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+	if (!handle) {
+		/* Failed to open trace.dat file */
+	}
+...
+	tracecmd_close(hadle);
+
+--
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-libtracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+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
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
-- 
2.28.0


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

* [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers.
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
                   ` (3 preceding siblings ...)
  2020-12-23  4:34 ` [PATCH 4/6] trace-cmd library man pages: Open and close " Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  2021-01-13 22:13   ` Steven Rostedt
  2020-12-23  4:34 ` [PATCH 6/6] trace-cmd library man pages: Read tracing instances from a trace file Tzvetomir Stoyanov (VMware)
  5 siblings, 1 reply; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
 tracecmd_pair_peer()
 tracecmd_unpair_peer()
 tracecmd_get_traceid()
 tracecmd_get_guest_cpumap()

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

diff --git a/Documentation/libtracecmd/libtracecmd-peer.3.txt b/Documentation/libtracecmd/libtracecmd-peer.3.txt
new file mode 100644
index 00000000..af0bf5dc
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd-peer.3.txt
@@ -0,0 +1,149 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+tracecmd_pair_peer, tracecmd_unpair_peer, tracecmd_get_traceid,
+tracecmd_get_guest_cpumap - Manage trace session with multiple trace peers,
+recorded in multiple trace files.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+int *tracecmd_pair_peer*(struct tracecmd_input pass:[*]_handle_, struct tracecmd_input pass:[*]_peer_);
+void *tracecmd_unpair_peer*(struct tracecmd_input pass:[*]_handle_);
+unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_);
+int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to manage trace session with multiple trace
+peers, like in tracing kernels of host and guests machines. The trace data
+of each peer from the session is recorded in separate trace file.
+Information about peers from the session is stored in the metadata of each
+trace file. These APIs use that information to extract and synchronize
+the trace data.
+
+The _tracecmd_pair_peer()_ function pairs two tracecmd_input handlers,
+associated with two trace files from same trace session. This API must
+be called before _tracecmd_init_data()(3)_, as the initialisation of
+the trace data depends on that. If there is a tracing peer, the event
+timestamps are recalculated in order to be in the same time space.
+
+The _tracecmd_unpair_peer()_ function unpairs a peer from _handle_,
+previously paired with _tracecmd_pair_peer()_.
+
+The _tracecmd_get_traceid()_ function returns the trace ID stored in
+trace file metadata, associated with _handle_. Each peer from a trace
+session has an ID unique for that peer and that trace session only.
+This ID is used to match multiple trace files recorded in a same trace
+session.
+
+The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest
+VCPU to the host process, stored in the metadata of the trace file
+associated with _handle_. This information is gathered during a host-guest
+trace session and is stored in host trace file. The _trace_id_ parameter is
+the trace ID of the guest in this particular trace session. If a guest
+with that ID was part of that session, its VCPU to host process mapping
+is in the host trace file and the information is returned in _name_,
+_vcpu_count_ and _cpu_pid_ parameters. In _name_ is returned the name
+of the guest, in _vcpu_count_ is returned the count of VCPUs of that
+guest and in _cpu_pid_ array is returned the VCPU to host process mapping.
+The array is of size _vcpu_count_ where the index is VCPU and the value
+is PID of the host process, running that VCPU. The _name_, _vcpu_count_
+and _cpu_pid_ values must *not* be freed.
+
+RETURN VALUE
+------------
+The _tracecmd_pair_peer()_ function returns 1, if a peer is already
+paired, -1 in case of an error or 0 otherwise.
+
+The tracecmd_get_traceid() function returns a 64 bit trace ID.
+
+The _tracecmd_get_guest_cpumap()_ function returns -1 in case of
+an error or 0 otherwise. If 0 is returned, in the _name_, _vcpu_count_
+and _cpu_pid_ parameters is stored requested information.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <trace-cmd.h>
+...
+struct tracecmd_input *host = tracecmd_open_head("trace.dat");
+	if (!host) {
+		/* Failed to open host trace file */
+	}
+	tracecmd_init_data(host);
+
+struct tracecmd_input *guest = tracecmd_open_head("trace-Guest.dat");
+	if (!guest) {
+		/* Failed to open guest trace file */
+	}
+
+unsigned long long guest_id = tracecmd_get_traceid(guest);
+int *cpu_pid;
+char *name;
+int vcount;
+
+	if (!tracecmd_get_guest_cpumap(host, guest_id, &name, &vcount, &cpu_pid)) {
+		/* The Host and a guest with name was part of the same trace session.
+		 * Got guest VCPU to host PID mapping.
+		 */
+		if (!tracecmd_pair_peer(guest, host)) {
+			/* Successfully paired host to the guest handler */
+			tracecmd_init_data(guest);
+			...
+			tracecmd_unpair_peer(guest);
+		}
+	}
+
+...
+	tracecmd_close(guest);
+	tracecmd_close(hadle);
+
+--
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-libtracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+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
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
-- 
2.28.0


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

* [PATCH 6/6] trace-cmd library man pages: Read tracing instances from a trace file.
  2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
                   ` (4 preceding siblings ...)
  2020-12-23  4:34 ` [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers Tzvetomir Stoyanov (VMware)
@ 2020-12-23  4:34 ` Tzvetomir Stoyanov (VMware)
  5 siblings, 0 replies; 10+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2020-12-23  4:34 UTC (permalink / raw)
  To: rostedt; +Cc: linux-trace-devel

Documented APIs:
 tracecmd_buffer_instances()
 tracecmd_buffer_instance_name()
 tracecmd_buffer_instance_handle()

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

diff --git a/Documentation/libtracecmd/libtracecmd-instances.3.txt b/Documentation/libtracecmd/libtracecmd-instances.3.txt
new file mode 100644
index 00000000..eff7e3ec
--- /dev/null
+++ b/Documentation/libtracecmd/libtracecmd-instances.3.txt
@@ -0,0 +1,129 @@
+libtracecmd(3)
+=============
+
+NAME
+----
+tracecmd_buffer_instances, tracecmd_buffer_instance_name, tracecmd_buffer_instance_handle
+- Read tracing instances from a trace file.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <trace-cmd.h>*
+
+int *tracecmd_buffer_instances*(struct tracecmd_input pass:[*]_handle_);
+const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_);
+struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_);
+--
+
+DESCRIPTION
+-----------
+This set of APIs can be used to get information and read tracing data
+from tracing instances stored in a trace file.
+
+The _tracecmd_buffer_instances()_ function gets the number of tracing
+instances recorded in a trace file. The top instance is not counted.
+The _handle_ is a tracecmd_input handler returned by
+_tracecmd_open_head()_.
+
+The _tracecmd_buffer_instance_name()_ function gets the name of the
+tracing instance with given index _indx_, recorded in a trace file.
+The _indx_ is a number in the interval [0 .. count -1], where count
+is the number returned by _tracecmd_buffer_instances()_. The _handle_
+is a tracecmd_input handler returned by _tracecmd_open_head()_.
+
+The _tracecmd_buffer_instance_handle()_ allocates and initializes a
+tracecmd_input hanlder, associated with trace instance with index
+_indx_ from a trace file.  The _handle_ is a tracecmd_input handler
+returned by _tracecmd_open_head()_. The _indx_ is a number in the
+interval [0 .. count -1], where count is the number returned by
+_tracecmd_buffer_instances()_.
+
+RETURN VALUE
+------------
+The _tracecmd_buffer_instances()_ function returns the number of tracing
+instances recorded in a trace file.
+
+The _tracecmd_buffer_instance_name()_ function returns a string, the name
+of a tracing instance, or NULL in case of an error The string must *not*
+be freed.
+
+The _tracecmd_buffer_instance_handle()_ function returns a pointer to
+newly allocated tracecmd_input handler or NULL in case if an error. The
+returned handler must be closed by _tracecmd_close()(3)_
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <trace-cmd.h>
+...
+struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+	if (!handle) {
+		/* Failed to open trace.dat file */
+	}
+...
+int num = tracecmd_buffer_instances(handle);
+
+	while(num) {
+		struct tracecmd_input *h;
+		char *name;
+
+		name = tracecmd_buffer_instance_name(handle, num);
+		if (!name) {
+			/* Failed to get name of instance num */
+		}
+		h = tracecmd_buffer_instance_handle(handle, num);
+		if (!h) {
+			/* Failed to initialize handler for instance num */
+		}
+
+		...
+		tracecmd_close(h);
+		num--;
+	}
+...
+	tracecmd_close(hadle);
+
+--
+FILES
+-----
+[verse]
+--
+*trace-cmd.h*
+	Header file to include in order to have access to the library APIs.
+*-libtracecmd*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtracefs(3)_,
+_libtraceevent(3)_,
+_trace-cmd(1)_
+_trace-cmd.dat(5)_
+
+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
+-------
+libtracecmd is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
+
+COPYING
+-------
+Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
-- 
2.28.0


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

* Re: [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers.
  2020-12-23  4:34 ` [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers Tzvetomir Stoyanov (VMware)
@ 2021-01-13 22:13   ` Steven Rostedt
  2021-01-15  5:02     ` Tzvetomir Stoyanov
  0 siblings, 1 reply; 10+ messages in thread
From: Steven Rostedt @ 2021-01-13 22:13 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel


I'm assuming that you can pair multiple guests with a single host?

That is, can we have:


	bool g1 = false, g2 = false;

	host = tracecmd_open_head("trace.dat");
	tracecmd_init_data(host);
	guest1 = tracecmd_open_head("trace-Guest-1.dat");
	guest2 = tracecmd_open_head("trace-Guest-2.dat");

	guest_id_1 = tracecmd_get_traceid(guest1);
	guest_id_2 = tracecmd_get_traceid(guest1);

	if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name1, &vcount1, &cpu_pids1)
		g1 = !tracecmd_init_data(guest1);

	if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name2, &vcount2, &cpu_pids2)
		g2 = !tracecmd_init_data(guest2);

	if (g1) {
		int i;
		for (i = 0; i < vcount1; i++) {
			printf("Host task id %d maps to guest %s cpu %d\n",
				cpu_pids1[i], name1, i);
		}
		tracecmd_unpair_peer(guest1);
	}

	if (g2) {
		int i;
		for (i = 0; i < vcount2; i++) {
			printf("Host task id %d maps to guest %s cpu %d\n",
				cpu_pids2[i], name2, i);
		}
		tracecmd_unpair_peer(guest2);
	}

And use something like the above for the example?

-- Steve


On Wed, 23 Dec 2020 06:34:28 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <trace-cmd.h>
> +...
> +struct tracecmd_input *host = tracecmd_open_head("trace.dat");
> +	if (!host) {
> +		/* Failed to open host trace file */
> +	}
> +	tracecmd_init_data(host);
> +
> +struct tracecmd_input *guest = tracecmd_open_head("trace-Guest.dat");
> +	if (!guest) {
> +		/* Failed to open guest trace file */
> +	}
> +
> +unsigned long long guest_id = tracecmd_get_traceid(guest);
> +int *cpu_pid;
> +char *name;
> +int vcount;
> +
> +	if (!tracecmd_get_guest_cpumap(host, guest_id, &name, &vcount, &cpu_pid)) {
> +		/* The Host and a guest with name was part of the same trace session.
> +		 * Got guest VCPU to host PID mapping.
> +		 */
> +		if (!tracecmd_pair_peer(guest, host)) {
> +			/* Successfully paired host to the guest handler */
> +			tracecmd_init_data(guest);
> +			...
> +			tracecmd_unpair_peer(guest);
> +		}
> +	}
> +
> +...
> +	tracecmd_close(guest);
> +	tracecmd_close(hadle);
> +
> +--

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

* Re: [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file.
  2020-12-23  4:34 ` [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file Tzvetomir Stoyanov (VMware)
@ 2021-01-13 22:18   ` Steven Rostedt
  0 siblings, 0 replies; 10+ messages in thread
From: Steven Rostedt @ 2021-01-13 22:18 UTC (permalink / raw)
  To: Tzvetomir Stoyanov (VMware); +Cc: linux-trace-devel


I think the below example should be also used in the tracecmd_open_head()
man page. That's because the current example in tracecmd_open_head() is
rather useless as nothing really can be done without the
tracecmd_init_data() call. By using the below example in the
tracecmd_open_head() page, it will show people a more informative way of
using that call.

Note, these man pages are already applied, any update should be done on top
of the current repo.

-- Steve


On Wed, 23 Dec 2020 06:34:26 +0200
"Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:

> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <trace-cmd.h>
> +...
> +struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
> +	if (!handle) {
> +		/* Failed to open trace.dat file */
> +	}
> +...
> +unsigned long long offset = 0;
> +struct tep_record *rec;
> +int cpu = 0;
> +
> +	if (tracecmd_init_data(handle) < 0) {
> +		/* Failed to initialize hadle for reading the trace data */
> +	}
> +
> +	rec = tracecmd_read_cpu_first(handle, cpu);
> +	while (rec) {
> +		...
> +		if ( /* some interesting record noticed */) {
> +			/* store the offset of the interesting record */
> +			offset = rec->offset;
> +		}
> +		...
> +		tracecmd_free_record(rec);
> +		rec = tracecmd_read_data(handle, cpu);
> +	}
> +	...
> +	if (offset) {
> +		rec = tracecmd_read_at(handle, offset, &cpu);
> +		if (rec) {
> +			/* Got record at offset on cpu */
> +			...
> +			tracecmd_free_record(rec);
> +		}
> +	}
> +
> +...
> +	tracecmd_close(hadle);
> +

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

* Re: [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers.
  2021-01-13 22:13   ` Steven Rostedt
@ 2021-01-15  5:02     ` Tzvetomir Stoyanov
  0 siblings, 0 replies; 10+ messages in thread
From: Tzvetomir Stoyanov @ 2021-01-15  5:02 UTC (permalink / raw)
  To: Steven Rostedt; +Cc: Linux Trace Devel

On Thu, Jan 14, 2021 at 12:13 AM Steven Rostedt <rostedt@goodmis.org> wrote:
>
>
> I'm assuming that you can pair multiple guests with a single host?

Yes, this use case is tested using KernelShark. I'll extend the
example in the man page.

>
> That is, can we have:
>
>
>         bool g1 = false, g2 = false;
>
>         host = tracecmd_open_head("trace.dat");
>         tracecmd_init_data(host);
>         guest1 = tracecmd_open_head("trace-Guest-1.dat");
>         guest2 = tracecmd_open_head("trace-Guest-2.dat");
>
>         guest_id_1 = tracecmd_get_traceid(guest1);
>         guest_id_2 = tracecmd_get_traceid(guest1);
>
>         if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name1, &vcount1, &cpu_pids1)
>                 g1 = !tracecmd_init_data(guest1);
>
>         if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name2, &vcount2, &cpu_pids2)
>                 g2 = !tracecmd_init_data(guest2);
>
>         if (g1) {
>                 int i;
>                 for (i = 0; i < vcount1; i++) {
>                         printf("Host task id %d maps to guest %s cpu %d\n",
>                                 cpu_pids1[i], name1, i);
>                 }
>                 tracecmd_unpair_peer(guest1);
>         }
>
>         if (g2) {
>                 int i;
>                 for (i = 0; i < vcount2; i++) {
>                         printf("Host task id %d maps to guest %s cpu %d\n",
>                                 cpu_pids2[i], name2, i);
>                 }
>                 tracecmd_unpair_peer(guest2);
>         }
>
> And use something like the above for the example?
>
> -- Steve
>
>
> On Wed, 23 Dec 2020 06:34:28 +0200
> "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com> wrote:
>
> > +EXAMPLE
> > +-------
> > +[source,c]
> > +--
> > +#include <trace-cmd.h>
> > +...
> > +struct tracecmd_input *host = tracecmd_open_head("trace.dat");
> > +     if (!host) {
> > +             /* Failed to open host trace file */
> > +     }
> > +     tracecmd_init_data(host);
> > +
> > +struct tracecmd_input *guest = tracecmd_open_head("trace-Guest.dat");
> > +     if (!guest) {
> > +             /* Failed to open guest trace file */
> > +     }
> > +
> > +unsigned long long guest_id = tracecmd_get_traceid(guest);
> > +int *cpu_pid;
> > +char *name;
> > +int vcount;
> > +
> > +     if (!tracecmd_get_guest_cpumap(host, guest_id, &name, &vcount, &cpu_pid)) {
> > +             /* The Host and a guest with name was part of the same trace session.
> > +              * Got guest VCPU to host PID mapping.
> > +              */
> > +             if (!tracecmd_pair_peer(guest, host)) {
> > +                     /* Successfully paired host to the guest handler */
> > +                     tracecmd_init_data(guest);
> > +                     ...
> > +                     tracecmd_unpair_peer(guest);
> > +             }
> > +     }
> > +
> > +...
> > +     tracecmd_close(guest);
> > +     tracecmd_close(hadle);
> > +
> > +--



-- 
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center

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

end of thread, back to index

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-23  4:34 [PATCH 0/6] libtracecmd man pages Tzvetomir Stoyanov (VMware)
2020-12-23  4:34 ` [PATCH 1/6] trace-cmd: " Tzvetomir Stoyanov (VMware)
2020-12-23  4:34 ` [PATCH 2/6] trace-cmd: Update the RESOURCES section of the trace-cmd " Tzvetomir Stoyanov (VMware)
2020-12-23  4:34 ` [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file Tzvetomir Stoyanov (VMware)
2021-01-13 22:18   ` Steven Rostedt
2020-12-23  4:34 ` [PATCH 4/6] trace-cmd library man pages: Open and close " Tzvetomir Stoyanov (VMware)
2020-12-23  4:34 ` [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers Tzvetomir Stoyanov (VMware)
2021-01-13 22:13   ` Steven Rostedt
2021-01-15  5:02     ` Tzvetomir Stoyanov
2020-12-23  4:34 ` [PATCH 6/6] trace-cmd library man pages: Read tracing instances from a trace file Tzvetomir Stoyanov (VMware)

Linux-Trace-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-trace-devel/0 linux-trace-devel/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-trace-devel linux-trace-devel/ https://lore.kernel.org/linux-trace-devel \
		linux-trace-devel@vger.kernel.org
	public-inbox-index linux-trace-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-trace-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git