* [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
| 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 related [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 +-
| 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
-------
--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 related [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 related [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 related [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 related [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 related [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, other threads:[~2021-01-15 5:03 UTC | newest]
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)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).