Skip to contentSkip to conversation

libtracecmd man pages.

PATCH In review Tzvetomir Stoyanov (VMware) 2 participants 10 messages Dec 23, 2020 – Jan 15, 2021 Documentation

lore
Share & tools
lore
#0 lore raw

cover libtracecmd man pages.

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%)
Signature · 1 line
2.28.0
#1 lore raw

PATCH 1/6 trace-cmd: libtracecmd man pages

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.

---
 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%)
Documentation/Makefile +11 -86
index f2c32640..8e979ece 100644
@@ -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:
Documentation/libtracecmd/Makefile new file +34 -0
new file mode 100644
index 00000000..196cac7c
@@ -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:
Documentation/libtracecmd/libtracecmd.3.txt new file +83 -0

83 lines not on this page · raw message

Documentation/trace-cmd/Makefile new file +44 -0

44 lines not on this page · raw message

Documentation/trace-cmd/trace-cmd-check-events.1.txt renamed from Documentation/trace-cmd-check-events.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-check-events.1.txt
rename to Documentation/trace-cmd/trace-cmd-check-events.1.txt
Documentation/trace-cmd/trace-cmd-clear.1.txt renamed from Documentation/trace-cmd-clear.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-clear.1.txt
rename to Documentation/trace-cmd/trace-cmd-clear.1.txt
Documentation/trace-cmd/trace-cmd-dump.1.txt renamed from Documentation/trace-cmd-dump.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-dump.1.txt
rename to Documentation/trace-cmd/trace-cmd-dump.1.txt
Documentation/trace-cmd/trace-cmd-extract.1.txt renamed from Documentation/trace-cmd-extract.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-extract.1.txt
rename to Documentation/trace-cmd/trace-cmd-extract.1.txt
Documentation/trace-cmd/trace-cmd-hist.1.txt renamed from Documentation/trace-cmd-hist.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-hist.1.txt
rename to Documentation/trace-cmd/trace-cmd-hist.1.txt
Documentation/trace-cmd/trace-cmd-list.1.txt renamed from Documentation/trace-cmd-list.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-list.1.txt
rename to Documentation/trace-cmd/trace-cmd-list.1.txt
Documentation/trace-cmd/trace-cmd-listen.1.txt renamed from Documentation/trace-cmd-listen.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-listen.1.txt
rename to Documentation/trace-cmd/trace-cmd-listen.1.txt
Documentation/trace-cmd/trace-cmd-mem.1.txt renamed from Documentation/trace-cmd-mem.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-mem.1.txt
rename to Documentation/trace-cmd/trace-cmd-mem.1.txt
Documentation/trace-cmd/trace-cmd-options.1.txt renamed from Documentation/trace-cmd-options.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-options.1.txt
rename to Documentation/trace-cmd/trace-cmd-options.1.txt
Documentation/trace-cmd/trace-cmd-profile.1.txt renamed from Documentation/trace-cmd-profile.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-profile.1.txt
rename to Documentation/trace-cmd/trace-cmd-profile.1.txt
Documentation/trace-cmd/trace-cmd-record.1.txt renamed from Documentation/trace-cmd-record.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-record.1.txt
rename to Documentation/trace-cmd/trace-cmd-record.1.txt
Documentation/trace-cmd/trace-cmd-report.1.txt renamed from Documentation/trace-cmd-report.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-report.1.txt
rename to Documentation/trace-cmd/trace-cmd-report.1.txt
Documentation/trace-cmd/trace-cmd-reset.1.txt renamed from Documentation/trace-cmd-reset.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-reset.1.txt
rename to Documentation/trace-cmd/trace-cmd-reset.1.txt
Documentation/trace-cmd/trace-cmd-restore.1.txt renamed from Documentation/trace-cmd-restore.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-restore.1.txt
rename to Documentation/trace-cmd/trace-cmd-restore.1.txt
Documentation/trace-cmd/trace-cmd-set.1.txt renamed from Documentation/trace-cmd-set.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-set.1.txt
rename to Documentation/trace-cmd/trace-cmd-set.1.txt
Documentation/trace-cmd/trace-cmd-show.1.txt renamed from Documentation/trace-cmd-show.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-show.1.txt
rename to Documentation/trace-cmd/trace-cmd-show.1.txt
Documentation/trace-cmd/trace-cmd-snapshot.1.txt renamed from Documentation/trace-cmd-snapshot.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-snapshot.1.txt
rename to Documentation/trace-cmd/trace-cmd-snapshot.1.txt
Documentation/trace-cmd/trace-cmd-split.1.txt renamed from Documentation/trace-cmd-split.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-split.1.txt
rename to Documentation/trace-cmd/trace-cmd-split.1.txt
Documentation/trace-cmd/trace-cmd-stack.1.txt renamed from Documentation/trace-cmd-stack.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-stack.1.txt
rename to Documentation/trace-cmd/trace-cmd-stack.1.txt
Documentation/trace-cmd/trace-cmd-start.1.txt renamed from Documentation/trace-cmd-start.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-start.1.txt
rename to Documentation/trace-cmd/trace-cmd-start.1.txt
Documentation/trace-cmd/trace-cmd-stat.1.txt renamed from Documentation/trace-cmd-stat.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-stat.1.txt
rename to Documentation/trace-cmd/trace-cmd-stat.1.txt
Documentation/trace-cmd/trace-cmd-stop.1.txt renamed from Documentation/trace-cmd-stop.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-stop.1.txt
rename to Documentation/trace-cmd/trace-cmd-stop.1.txt
Documentation/trace-cmd/trace-cmd-stream.1.txt renamed from Documentation/trace-cmd-stream.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd-stream.1.txt
rename to Documentation/trace-cmd/trace-cmd-stream.1.txt
Documentation/trace-cmd/trace-cmd.1.txt renamed from Documentation/trace-cmd.1.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd.1.txt
rename to Documentation/trace-cmd/trace-cmd.1.txt
Documentation/trace-cmd/trace-cmd.dat.5.txt renamed from Documentation/trace-cmd.dat.5.txt +0 -0
similarity index 100%
rename from Documentation/trace-cmd.dat.5.txt
rename to Documentation/trace-cmd/trace-cmd.dat.5.txt
scripts/utils.mk +42 -0

57 lines not on this page · raw message

Signature · 1 line
2.28.0
#2 lore raw

PATCH 2/6 trace-cmd: Update the RESOURCES section of the trace-cmd man pages

In reply to Tzvetomir Stoyanov (VMware)

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/

---
 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(-)
Documentation/trace-cmd/trace-cmd-check-events.1.txt +1 -1
index 73ec1a8b..c98ff3c6 100644
@@ -36,7 +36,7 @@ Written by Vaibhav Nagarnaik, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-clear.1.txt +1 -1
index a0ae36e9..74236960 100644
@@ -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
Documentation/trace-cmd/trace-cmd-dump.1.txt +1 -1
index e29bfe86..71b8e655 100644
@@ -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
 -------
Documentation/trace-cmd/trace-cmd-extract.1.txt +1 -1
index 917a6371..4444733d 100644
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-hist.1.txt +1 -1
index b17936d0..169f8d7b 100644
@@ -41,7 +41,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-list.1.txt +1 -1
index bba45ea4..0ad62643 100644
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-listen.1.txt +1 -1
index a242c49e..8697328c 100644
@@ -49,7 +49,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-mem.1.txt +1 -1
index 9e811b91..90e430b8 100644
@@ -65,7 +65,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-options.1.txt +1 -1
index e7faf320..bcdf0533 100644
@@ -26,7 +26,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-profile.1.txt +1 -1
index 3ffce86b..0d1dd8e8 100644
@@ -667,7 +667,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-record.1.txt +1 -1
index 99d1a156..643659ad 100644
@@ -461,7 +461,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-report.1.txt +1 -1
index de616cf4..766c9a57 100644
@@ -487,7 +487,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-reset.1.txt +1 -1
index bff45300..eee86751 100644
@@ -107,7 +107,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-restore.1.txt +1 -1
index 290b0acd..ebcbb1b6 100644
@@ -96,7 +96,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-set.1.txt +1 -1
index 2f95e07f..931d3abd 100644
@@ -255,7 +255,7 @@ Written by Tzvetomir Stoyanov (VMware) <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-show.1.txt +1 -1
index b17851ef..ea2fda28 100644
@@ -91,7 +91,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-snapshot.1.txt +1 -1
index 6d94ada0..0a34bcd9 100644
@@ -56,7 +56,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-split.1.txt +1 -1
index b8308bbc..25385796 100644
@@ -98,7 +98,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-stack.1.txt +1 -1
index 6b5f0c08..a00c6900 100644
@@ -36,7 +36,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-start.1.txt +1 -1
index 07f2ed3a..03c5d127 100644
@@ -42,7 +42,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-stat.1.txt +1 -1
index 2f1a9c8b..e5fccce9 100644
@@ -57,7 +57,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-stop.1.txt +1 -1
index 1955fa71..313192c3 100644
@@ -54,7 +54,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd-stream.1.txt +1 -1
index 10094028..f83652b8 100644
@@ -41,7 +41,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd.1.txt +1 -1
index 5548ed27..b330b4fe 100644
@@ -80,7 +80,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Documentation/trace-cmd/trace-cmd.dat.5.txt +1 -1
index d849439b..8d285353 100644
@@ -258,7 +258,7 @@ Written by Steven Rostedt, <[email protected]>
 
 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
 -------
Signature · 1 line
2.28.0
#3 lore raw

PATCH 3/6 trace-cmd library man pages: Read recorded events from a trace file.

In reply to Tzvetomir Stoyanov (VMware)

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

---
 .../libtracecmd/libtracecmd-record.3.txt      | 152 ++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 Documentation/libtracecmd/libtracecmd-record.3.txt
Documentation/libtracecmd/libtracecmd-record.3.txt new file +152 -0
new file mode 100644
index 00000000..194b1670
@@ -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* <[email protected]>
+*Tzvetomir Stoyanov* <[email protected]>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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).
Signature · 1 line
2.28.0
#4 lore raw

Re: [PATCH 3/6] trace-cmd library man pages: Read recorded events from a trace file.

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

Quoted 43 lines · On Wed, 23 Dec 2020 06:34:26 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracecmd/libtracecmd-record.3.txt new file +43 -0
+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);
+
#5 lore raw

PATCH 4/6 trace-cmd library man pages: Open and close trace file.

In reply to Tzvetomir Stoyanov (VMware)

Documented APIs:
tracecmd_open_head()
tracecmd_close()

---
 .../libtracecmd/libtracecmd-files.3.txt       | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 Documentation/libtracecmd/libtracecmd-files.3.txt
Documentation/libtracecmd/libtracecmd-files.3.txt new file +92 -0
new file mode 100644
index 00000000..7cf12ea4
@@ -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* <[email protected]>
+*Tzvetomir Stoyanov* <[email protected]>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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).
Signature · 1 line
2.28.0
#6 lore raw

PATCH 5/6 trace-cmd library man pages: Manage trace session with multiple trace peers.

In reply to Tzvetomir Stoyanov (VMware)

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

---
 .../libtracecmd/libtracecmd-peer.3.txt        | 149 ++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 Documentation/libtracecmd/libtracecmd-peer.3.txt
Documentation/libtracecmd/libtracecmd-peer.3.txt new file +149 -0
new file mode 100644
index 00000000..af0bf5dc
@@ -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* <[email protected]>
+*Tzvetomir Stoyanov* <[email protected]>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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).
Signature · 1 line
2.28.0
#7 lore raw

Re: [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers.

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

Quoted 39 lines · On Wed, 23 Dec 2020 06:34:28 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracecmd/libtracecmd-peer.3.txt new file +39 -0
+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);
+
+--
#8 lore raw

Re: [PATCH 5/6] trace-cmd library man pages: Manage trace session with multiple trace peers.

Quoted 3 lines · Steven Rostedt

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.

Quoted 85 lines

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

Quoted 39 lines · On Wed, 23 Dec 2020 06:34:28 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracecmd/libtracecmd-peer.3.txt new file +39 -0
+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);
+
+--
Signature · 2 lines
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
#9 lore raw

PATCH 6/6 trace-cmd library man pages: Read tracing instances from a trace file.

In reply to Tzvetomir Stoyanov (VMware)

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

---
 .../libtracecmd/libtracecmd-instances.3.txt   | 129 ++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 Documentation/libtracecmd/libtracecmd-instances.3.txt
Documentation/libtracecmd/libtracecmd-instances.3.txt new file +129 -0
new file mode 100644
index 00000000..eff7e3ec
@@ -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* <[email protected]>
+*Tzvetomir Stoyanov* <[email protected]>
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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).
Signature · 1 line
2.28.0