@@ -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:
new file mode 100644
@@ -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:
new file mode 100644
@@ -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).
new file mode 100644
@@ -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:
similarity index 100%
rename from Documentation/trace-cmd-check-events.1.txt
rename to Documentation/trace-cmd/trace-cmd-check-events.1.txt
similarity index 100%
rename from Documentation/trace-cmd-clear.1.txt
rename to Documentation/trace-cmd/trace-cmd-clear.1.txt
similarity index 100%
rename from Documentation/trace-cmd-dump.1.txt
rename to Documentation/trace-cmd/trace-cmd-dump.1.txt
similarity index 100%
rename from Documentation/trace-cmd-extract.1.txt
rename to Documentation/trace-cmd/trace-cmd-extract.1.txt
similarity index 100%
rename from Documentation/trace-cmd-hist.1.txt
rename to Documentation/trace-cmd/trace-cmd-hist.1.txt
similarity index 100%
rename from Documentation/trace-cmd-list.1.txt
rename to Documentation/trace-cmd/trace-cmd-list.1.txt
similarity index 100%
rename from Documentation/trace-cmd-listen.1.txt
rename to Documentation/trace-cmd/trace-cmd-listen.1.txt
similarity index 100%
rename from Documentation/trace-cmd-mem.1.txt
rename to Documentation/trace-cmd/trace-cmd-mem.1.txt
similarity index 100%
rename from Documentation/trace-cmd-options.1.txt
rename to Documentation/trace-cmd/trace-cmd-options.1.txt
similarity index 100%
rename from Documentation/trace-cmd-profile.1.txt
rename to Documentation/trace-cmd/trace-cmd-profile.1.txt
similarity index 100%
rename from Documentation/trace-cmd-record.1.txt
rename to Documentation/trace-cmd/trace-cmd-record.1.txt
similarity index 100%
rename from Documentation/trace-cmd-report.1.txt
rename to Documentation/trace-cmd/trace-cmd-report.1.txt
similarity index 100%
rename from Documentation/trace-cmd-reset.1.txt
rename to Documentation/trace-cmd/trace-cmd-reset.1.txt
similarity index 100%
rename from Documentation/trace-cmd-restore.1.txt
rename to Documentation/trace-cmd/trace-cmd-restore.1.txt
similarity index 100%
rename from Documentation/trace-cmd-set.1.txt
rename to Documentation/trace-cmd/trace-cmd-set.1.txt
similarity index 100%
rename from Documentation/trace-cmd-show.1.txt
rename to Documentation/trace-cmd/trace-cmd-show.1.txt
similarity index 100%
rename from Documentation/trace-cmd-snapshot.1.txt
rename to Documentation/trace-cmd/trace-cmd-snapshot.1.txt
similarity index 100%
rename from Documentation/trace-cmd-split.1.txt
rename to Documentation/trace-cmd/trace-cmd-split.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stack.1.txt
rename to Documentation/trace-cmd/trace-cmd-stack.1.txt
similarity index 100%
rename from Documentation/trace-cmd-start.1.txt
rename to Documentation/trace-cmd/trace-cmd-start.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stat.1.txt
rename to Documentation/trace-cmd/trace-cmd-stat.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stop.1.txt
rename to Documentation/trace-cmd/trace-cmd-stop.1.txt
similarity index 100%
rename from Documentation/trace-cmd-stream.1.txt
rename to Documentation/trace-cmd/trace-cmd-stream.1.txt
similarity index 100%
rename from Documentation/trace-cmd.1.txt
rename to Documentation/trace-cmd/trace-cmd.1.txt
similarity index 100%
rename from Documentation/trace-cmd.dat.5.txt
rename to Documentation/trace-cmd/trace-cmd.dat.5.txt
@@ -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
Initial implementation of trace-cmd library man pages. trace-cmd/Documentation directory is reorganized to hold both trace-cmd application and library man pages, each in its own subdirectory. The first libtracecmd man page is implemented: "man libtracecmd" with a list of all library APIs. Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com> --- Documentation/Makefile | 97 +++---------------- Documentation/libtracecmd/Makefile | 34 +++++++ Documentation/libtracecmd/libtracecmd.3.txt | 83 ++++++++++++++++ Documentation/trace-cmd/Makefile | 44 +++++++++ .../trace-cmd-check-events.1.txt | 0 .../{ => trace-cmd}/trace-cmd-clear.1.txt | 0 .../{ => trace-cmd}/trace-cmd-dump.1.txt | 0 .../{ => trace-cmd}/trace-cmd-extract.1.txt | 0 .../{ => trace-cmd}/trace-cmd-hist.1.txt | 0 .../{ => trace-cmd}/trace-cmd-list.1.txt | 0 .../{ => trace-cmd}/trace-cmd-listen.1.txt | 0 .../{ => trace-cmd}/trace-cmd-mem.1.txt | 0 .../{ => trace-cmd}/trace-cmd-options.1.txt | 0 .../{ => trace-cmd}/trace-cmd-profile.1.txt | 0 .../{ => trace-cmd}/trace-cmd-record.1.txt | 0 .../{ => trace-cmd}/trace-cmd-report.1.txt | 0 .../{ => trace-cmd}/trace-cmd-reset.1.txt | 0 .../{ => trace-cmd}/trace-cmd-restore.1.txt | 0 .../{ => trace-cmd}/trace-cmd-set.1.txt | 0 .../{ => trace-cmd}/trace-cmd-show.1.txt | 0 .../{ => trace-cmd}/trace-cmd-snapshot.1.txt | 0 .../{ => trace-cmd}/trace-cmd-split.1.txt | 0 .../{ => trace-cmd}/trace-cmd-stack.1.txt | 0 .../{ => trace-cmd}/trace-cmd-start.1.txt | 0 .../{ => trace-cmd}/trace-cmd-stat.1.txt | 0 .../{ => trace-cmd}/trace-cmd-stop.1.txt | 0 .../{ => trace-cmd}/trace-cmd-stream.1.txt | 0 Documentation/{ => trace-cmd}/trace-cmd.1.txt | 0 .../{ => trace-cmd}/trace-cmd.dat.5.txt | 0 scripts/utils.mk | 42 ++++++++ 30 files changed, 214 insertions(+), 86 deletions(-) create mode 100644 Documentation/libtracecmd/Makefile create mode 100644 Documentation/libtracecmd/libtracecmd.3.txt create mode 100644 Documentation/trace-cmd/Makefile rename Documentation/{ => trace-cmd}/trace-cmd-check-events.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-clear.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-dump.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-extract.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-hist.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-list.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-listen.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-mem.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-options.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-profile.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-record.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-report.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-reset.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-restore.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-set.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-show.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-snapshot.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-split.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-stack.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-start.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-stat.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-stop.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd-stream.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd.1.txt (100%) rename Documentation/{ => trace-cmd}/trace-cmd.dat.5.txt (100%)