From patchwork Wed Dec 23 04:34:24 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987611
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 15E06C433E6
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:15 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id D6B8120936
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:14 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1726288AbgLWEfO (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:14 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56758 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1726282AbgLWEfO (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:14 -0500
Received: from mail-wr1-x431.google.com (mail-wr1-x431.google.com
 [IPv6:2a00:1450:4864:20::431])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8D80DC0613D6
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:33 -0800 (PST)
Received: by mail-wr1-x431.google.com with SMTP id m5so17293851wrx.9
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:33 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=c2Vt0gcY/s1rCKQnQVFkwQO6OAU+C95/f3sNY1H7X3I=;
        b=jOb7WflWVQgrv8kGiTtS4i6lIPXZdYqP+ajWKEsCqc9BOJ4YqcNKGDXoyO7rrmoGR5
         Z2GXz3xKO7os9X6EvRPG5R0Rgjua4ngl4oH7MacqRPZsIO5CRVViRoAhxvXYr+8GSszw
         a+A8fnXy8hqaG1N+RdVEkWkvj9VRd/SDXVxkqgnIhJ7wT8QNyHrBgUXQQvgglGNztgnU
         NFeO0YSw5YkLDkFgc9lU72F2sYnviMQsASU8HPb1X91Z63TIcUR1afFRFx8/CsltOecS
         DExpdw9RxFGPn8sOFXc8liKPbCKsnV/yl2xfvJgK6X2Sjpd+ABsDRsM3cr8WsTZQRMW7
         P8bQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=c2Vt0gcY/s1rCKQnQVFkwQO6OAU+C95/f3sNY1H7X3I=;
        b=rhq2nTI5OlZCaWmMH8nndVZBbBBgKTDqikmwAdM9dbbiAjUdzXtfCO0L7DRaiY37wm
         hiPUkzA/EgdYqf4yDJd/Qvj+2ptF+gXG8N/Q3Q5IrAURvKt0sk82ZTGZUArlwzW44i57
         HnTg5dNPPe6Mu/l2qTJ+Z1xFsZuQjXeDJPs/a27P8WPkZj+pmXKksgdxJG2ug8CCvmDp
         Siih12AQJTcgHUbVwUxGhyOXRvAGFXLvjInmoKTMxag5ALa3+FG57cmO8MVMS3WG+lsz
         52tKLtRET0BjXES892EZtLt007qVtrKlg+To54uoH3y11lmQIzhly4/9BGzR9BBOn600
         KtKw==
X-Gm-Message-State: AOAM531cn6sXt0p/zpYQTZyth15h/jwL/zwzgGpqrHIEndxTrCopnebR
        m1+fFlTe0VpQ4ZQxQq4iUJCNoesVwcG7oVo2
X-Google-Smtp-Source: 
 ABdhPJyoJcGa2ptQACYthVE/lcy7CCFvg2FOku8x2fHIWxD3gOLk9wMIw4Sat8CyuVBMKYyY4emDKw==
X-Received: by 2002:adf:f88d:: with SMTP id
 u13mr28016590wrp.161.1608698072162;
        Tue, 22 Dec 2020 20:34:32 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.31
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:31 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 1/6] trace-cmd: libtracecmd man pages
Date: Wed, 23 Dec 2020 06:34:24 +0200
Message-Id: <20201223043429.586162-2-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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

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

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

From patchwork Wed Dec 23 04:34:25 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987613
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id D48D7C433E0
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:15 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id A181320936
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:15 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1726387AbgLWEfP (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:15 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56764 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1726282AbgLWEfP (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:15 -0500
Received: from mail-wr1-x433.google.com (mail-wr1-x433.google.com
 [IPv6:2a00:1450:4864:20::433])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A57E4C061793
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:34 -0800 (PST)
Received: by mail-wr1-x433.google.com with SMTP id t16so17342004wra.3
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:34 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=2A3Wc9f8hLtGVJ3l1/ajqu2NiZDBm3z5GCAXR9PgX74=;
        b=CLNhVz6tIAoxLoUR4lhtJ2D2vcB4NGrguF7NoJqy1k0yy0JtqV6BjjgA26jlBT2HWT
         Br7qXPbpGF4RL5k+PHT+K8MinDj7eMhAb6Neylnb6vKXwN6erZUeMtikaEpr4Z1lt2wK
         SZHKF4e7PdUYirSmCoQsrzXLbMiW2BCXUO21+PbZ4foNkaaj8MP3vAKvBWETQtbZ/+t+
         doyy40JmC8oHhu3ZPCqPHjcYhmVKcqzky2XIBH6Fer69Iyu/MMyBZhsFcccwgyVuyiZn
         y87ZKjWLlZHtMBWPgjX/P61TFjwQLz4gFTE9E/I7IOoe8COMNag+AaJF+88G+VhEQG31
         bD/w==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=2A3Wc9f8hLtGVJ3l1/ajqu2NiZDBm3z5GCAXR9PgX74=;
        b=U1u6g46BLu5xLn+StjTZqUoKeYFxBnijAjzf3xx81lRFIMpfuBFn/ieyLM+SFClGpi
         u27jV0hUB83XlzeCxCfYTnGfD8KzhXTUOFZgzO5yZ/odFZ3WkfYA1LGdjaNHL+S8lpZY
         iYoWHkcv8XnVVCcmecCU51NsJcfulBkS5BuSF4eJHNvYQrZXVoIF27dsCSjHRxtIlmQ3
         3vAeATr442sG59/h/3vfbGX0fcpQwgpRsDAuQKP/upv4p+hcJs/4WaaVK6cdEz3mb87c
         saos6bS/nI7CMPLummsZQ5Kju40GAfsor8Ww8sabI2nYV4cyXX3ohZlYl6+nIfGTPWIC
         q8rA==
X-Gm-Message-State: AOAM532xJ9KDJFg1rfSJ+BxufD3SvRW+qmGW8pMh8LwgjlmveznCl5CR
        ujojZjt0NB1jejJbk5wE6qeeHH7+HrN/3EEE
X-Google-Smtp-Source: 
 ABdhPJxsvp0doEC7DdkgKXtqmVz6i0gYDPBbvXRdIljZAtBjMRABy+qFKRmnWPSnmAuWSCHYgBSjdQ==
X-Received: by 2002:a05:6000:1d2:: with SMTP id
 t18mr16526747wrx.412.1608698073237;
        Tue, 22 Dec 2020 20:34:33 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.32
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:32 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 2/6] trace-cmd: Update the RESOURCES section of the trace-cmd
 man pages
Date: Wed, 23 Dec 2020 06:34:25 +0200
Message-Id: <20201223043429.586162-3-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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

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

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

From patchwork Wed Dec 23 04:34:26 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987615
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 3C3EEC433DB
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:17 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id 11B1720936
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:17 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1726608AbgLWEfQ (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:16 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56768 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1726282AbgLWEfQ (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:16 -0500
Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com
 [IPv6:2a00:1450:4864:20::42f])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F0174C061794
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:35 -0800 (PST)
Received: by mail-wr1-x42f.google.com with SMTP id 91so17341526wrj.7
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:35 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=G4+1mxLSkD5Jqgk/EFsgqdRCUpuErUS8PeWMv+kyQw4=;
        b=jBHAMn28GPMz84tMnno3cj8B6DZdg2dfMmcHPoB2PnMxZXzi4cLG0GLt0xtQKwv54F
         HHEncXDT0FjPXhZUtry06wEXAsrvrZ5jH2xeIstyZWypC0+WR1MUkbxlMfgXjSA+bhC3
         Cx8L1eXatIfLb+flVu71VdrpMDWXtv22ex8075WN8ukBVQTuoZOiL5KY2x69rJNvVgHS
         jtz6JPrgU7sIResfBxTNB8mk214jMiLMYtdNuQT3mfZ8HoNjAn6/wxkP2U5bhzp2Q2kt
         9FKHvftbAft0QdHxAaxKS+yeFPCbu9Jaq8Cb8e1nzgn5CjnJIRJYEn2HvE20GkfJWnUi
         dfAQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=G4+1mxLSkD5Jqgk/EFsgqdRCUpuErUS8PeWMv+kyQw4=;
        b=XFTqtKAUMROhHtRAITZzlkyXf3Eg0GvSonYG1EiiD41gfAG6+zPjGKAWI/uZtR4YRy
         WVd9IG0MyGBUE/PN+7y3LLkOi4t/TTfYfWushNMur7k5Ek3Ti5cwA0XGqtEm6Tj86H3E
         UzZzkKs9USxa6TPPnG82c4S6vwM+Uivq+wmr1qdtUCXdlRdPVUNLaKSx6tkVmAgrXp6V
         tU3YDkDHJwhddw5LJLifaKzXpYQ1dJ/FBPt7J+VSNa9HMfvIA43zk8x3fhooENmj2etw
         Q9+f+QPFHb9jxg3PHJZFxUF5gLgDg/KJja99CT9EHjFJtGYvUsYgBe2rIx+TqCSc23+7
         QimA==
X-Gm-Message-State: AOAM533SN2u0tjW4C/5CQdaHBZ9IpjtBjxIbn4KN0uk4YECDlZvee3Vn
        AImsAUPKWtOzfcOOuoWMO38mdk2zGg3VB/77
X-Google-Smtp-Source: 
 ABdhPJx40dkhsSh1kEvvo37dodCWD3BEXbROpa0Tuw5e5uCjXKAuY+/8GSUPEgU9h9ya2optWlcbpQ==
X-Received: by 2002:a5d:4f90:: with SMTP id
 d16mr26943581wru.120.1608698074763;
        Tue, 22 Dec 2020 20:34:34 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.33
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:33 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 3/6] trace-cmd library man pages: Read recorded events from a
 trace file.
Date: Wed, 23 Dec 2020 06:34:26 +0200
Message-Id: <20201223043429.586162-4-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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).

From patchwork Wed Dec 23 04:34:27 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987617
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 4BBD2C433E9
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:18 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id 1FE6120936
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:35:18 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1726611AbgLWEfR (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:17 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56774 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1726282AbgLWEfR (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:17 -0500
Received: from mail-wr1-x430.google.com (mail-wr1-x430.google.com
 [IPv6:2a00:1450:4864:20::430])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 34236C06179C
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:37 -0800 (PST)
Received: by mail-wr1-x430.google.com with SMTP id r7so17324045wrc.5
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:37 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=CaRcTEAnNWGAxloB4vhh3lunl1bHioPlNW9EEp0sJWk=;
        b=eZCD/m2mHBK9ZKWzw3IKN33aRIZf2LGQ+zvE6uZq8gCIhxWEjbOfVErPWCb2Jh5MYH
         Oa4q1u0QRTiDuIRjZlcFu9+XHQiDcHrUDjLa77f+/UtTahLuk1it+xeNcQFnAr4C63jj
         QQMPBQ9Y0PS7fNp4aA55Ym8FLXWGqqYGsayjsupOF6ULC1sN7y+Qy4jghNdt15FQcNgO
         S5sUq+qWAoE5yUwyJTCKiPEmDBbdi7lPFMEJw48dGTZpg89cZxzW2P3FmwOdvSm1hsBt
         OBQm2AphQk/PRfiCysBG0UTO7xu8W/OnHNsTBJXHbD03LMPC2BNADpECLl5C5r/0Qocm
         eLgA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=CaRcTEAnNWGAxloB4vhh3lunl1bHioPlNW9EEp0sJWk=;
        b=IdZor7mU+z36cRcNRMHUM7RKKpKV1Yic2Rvx3Hj1IyRutq7k3Rfy17o6Sx8d9cg14V
         0uVDmmuw8tAiMDkwXLgpOrBiVIjaXzpqr6Zyejdb7CpBE5KZMhicKy0hxbC0fpACNKX3
         moJKXdd0NjsNF53H/y81GpPvs4z3LQLdeWxp/K8Dvyf/TFF1m7w2wZcDQb5/UlgHNog8
         IiRR2b3f7NsRbfqcLHVSqSm6LKuhMac2WnKWPZeVkTkSO9nSuJ7JUvyajCXlFHEw66SG
         sYlnVHntg11ASGSbyPY50LGXFAa3Tl02gfVRhSqjOv3l9ferTmBesCnpxPIh+nG8nyTM
         fImQ==
X-Gm-Message-State: AOAM530JWK0SP2Y7rfv+EnoO0sc0OYECuPalm1PFjrS2cUVJtwDkpsBT
        PDeT7Bv4bFbkh5X6qXX1Sl6k7t2R1xNJYrIK
X-Google-Smtp-Source: 
 ABdhPJx24iDdmAFP1U/lxKrpiBrD37OqqVIZlQg1wmk6HpGJZj+jpapbcOZAHwt5lr/K7zdXTOZcTA==
X-Received: by 2002:a5d:4104:: with SMTP id l4mr27757645wrp.340.1608698075935;
        Tue, 22 Dec 2020 20:34:35 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.34
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:35 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 4/6] trace-cmd library man pages: Open and close trace file.
Date: Wed, 23 Dec 2020 06:34:27 +0200
Message-Id: <20201223043429.586162-5-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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).

From patchwork Wed Dec 23 04:34:28 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987619
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 3CE9BC433E0
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:36:09 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id F2CAC20936
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:36:08 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1727013AbgLWEfx (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:53 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56862 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1725300AbgLWEfx (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:53 -0500
Received: from mail-wr1-x430.google.com (mail-wr1-x430.google.com
 [IPv6:2a00:1450:4864:20::430])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 43AF8C0617A6
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:38 -0800 (PST)
Received: by mail-wr1-x430.google.com with SMTP id t16so17342086wra.3
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:38 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=a8kbvUB7yNA5wDS1jH+zjTLod7h9tLFimIPqZVWdYJU=;
        b=WLvX97jGSQubXRd16bJc7yQPjgl8iXNOyKvl+BWvvJARAG3inkGPjL2sD6NoQq/rUv
         6eTaFNbTwC6srf1/zJiyJdj6ug5V4dj4XwxLPrGz7EfWvd04wdidcmYNParSffBKRU7e
         ZpKHnIh1J3pamYO/Xom6HAH6YP1CbTzVPVBKyf7FhxMxp9iuM3lyUyab+CKuR0C/Qmc2
         txcyfzSmjJ0BpnpwijOCmxal9OBWSQ0cmXqRIYVSDfaG+NhdEFb3v3xpssvlUOSGVlbN
         5OdrfrSHiid8BXcIWgxUWo3KXKF0iMksqe0zUbYrfXl7EM1SweZ8OvudRQeHugkqY7lf
         mUmQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=a8kbvUB7yNA5wDS1jH+zjTLod7h9tLFimIPqZVWdYJU=;
        b=slR69NW+VuOjlwGb87WLHSmaJZ1pVUYa01gxyj7qaC8OgWYX+4Wv/VtibgbFWfsCGd
         PIkfBEY6lY0X6D+ig7ZYF8gDbSFfrzM2A6s7LXP33E++FqA2sMDn869i1yF48MiHAu9D
         +u6UEfr1iLxSjfGGYPLjEdiJEXn4CI8v2rUlnnOS1Ch+Hv5/8LHrnodZpIeQrMLhvrFz
         E8oSlofaeIDuRVjwh1+42yK05ou8tYRsN9b5kL9s2ok5t6r/UpukW7m1XSN+XQDU/hOB
         pgZWM2wCw1Fzj7CaIsFVVxhcY+kPdMyJVpJLltWDNUCMX+FjxAWa/6vKna7CY/zmK+GB
         K96w==
X-Gm-Message-State: AOAM532Cisv7K96eUeUYXhXpt9qUzvxX8fvnsT7YPw1PnKNxEjytgwLA
        x9+tW/b63hiH2Rlvf2eedZElDj/4HpXsXBmQ
X-Google-Smtp-Source: 
 ABdhPJyT3bACNcUIz+gm7bs+mGqq/eAIrs1AeuTGwd5w2ZHy+KLw/QNltIOCUDw2FmsNq3IV6LPrqQ==
X-Received: by 2002:a5d:6749:: with SMTP id l9mr27528921wrw.395.1608698076991;
        Tue, 22 Dec 2020 20:34:36 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.36
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:36 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 5/6] trace-cmd library man pages: Manage trace session with
 multiple trace peers.
Date: Wed, 23 Dec 2020 06:34:28 +0200
Message-Id: <20201223043429.586162-6-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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).

From patchwork Wed Dec 23 04:34:29 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
X-Patchwork-Id: 11987621
Return-Path: <linux-trace-devel-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH,
	MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,
	USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 4E6C3C433E6
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:36:09 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id 1A65020E65
	for <linux-trace-devel@archiver.kernel.org>;
 Wed, 23 Dec 2020 04:36:09 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1725300AbgLWEfx (ORCPT
        <rfc822;linux-trace-devel@archiver.kernel.org>);
        Tue, 22 Dec 2020 23:35:53 -0500
Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56864 "EHLO
        lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1726068AbgLWEfx (ORCPT
        <rfc822;linux-trace-devel@vger.kernel.org>);
        Tue, 22 Dec 2020 23:35:53 -0500
Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com
 [IPv6:2a00:1450:4864:20::434])
        by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 700B2C061282
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:39 -0800 (PST)
Received: by mail-wr1-x434.google.com with SMTP id i9so17340534wrc.4
        for <linux-trace-devel@vger.kernel.org>;
 Tue, 22 Dec 2020 20:34:39 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=from:to:cc:subject:date:message-id:in-reply-to:references
         :mime-version:content-transfer-encoding;
        bh=hQKKW+dU4a3WmtsXmhKRYuX+tH83jmdgb3mS+hBgz/I=;
        b=If1c4rkWotzblYTzWmKK7nj5p69LHGlEatUEGBKtdAUJdUvjpjCk54brK7DA6JZ2qC
         x/Y7o4CMrbSBJPp8YLEp7srEyqvhqko5usCGLwIrjnYPHsPt0lgKf+aRNRxUnvDa0HTA
         ZhkscuA499CbqoUdr+QC6gzWnYFC1eJ7krtOT+3QiR9KLJUY5qnNGfX8L8BBasMvkIGA
         AbYUXsNLLq3NGq0f3sRxJ/1IWCXRpaBsvn+ct8HguWsunjRTQOkCG+NpfnOjCZlxiAJl
         pxXCR6dofetDw9ko813i2Z33G3ka7z41k93umLhRY8mhQmWHPzS/X33oXZs9ykX/q7tD
         /8BA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
         :references:mime-version:content-transfer-encoding;
        bh=hQKKW+dU4a3WmtsXmhKRYuX+tH83jmdgb3mS+hBgz/I=;
        b=av7PD6N1/uMOh9Dn0vBCxMvc92LlSTXPgVLT3dOvsUUXGpMB/hY1/UYKf2BDZe9l5L
         Sp6y1sYyL0T9/kYQUPW5YuvAJuvCkm80QN98eWhkzhNbL0AP4ZVP4gYtm8n1lQmT+sJb
         5tBNsKM0Wgi6ACIQvMUcJ1uv7KOZa7m05YQ/XY6WUQJ4efCnhtzo7IwjVCXEV1gSX9Hg
         Sb/x84pHEsZg6CcvsE3IXGgj32qMA6R/G1LCnxBR9Quc919Ja9o/SfCS66hfqcjuft2T
         F90QO8yq4ySk2B5o7s9x6KHeXvH5D21H1gL7ID6sTial3PrPfdAq265yHY9/K9Ze1GIJ
         rctA==
X-Gm-Message-State: AOAM533oo313/6YmK2DX2RxgiT0yj7qupwUslXKC1XhHUHCFXLytiA3E
        fBn/Ms+FUivA8p1dM1nDzeM=
X-Google-Smtp-Source: 
 ABdhPJyKF9r0cYK5mhxZ7gmBEaKU8Hir2YBRAvu6asZdE8KNGfWdVDx1dhdLum7yS9NJllD7eykGYw==
X-Received: by 2002:a5d:504b:: with SMTP id
 h11mr27124343wrt.337.1608698078230;
        Tue, 22 Dec 2020 20:34:38 -0800 (PST)
Received: from oberon.vmware.com ([83.222.187.186])
        by smtp.gmail.com with ESMTPSA id
 s13sm28909095wmj.28.2020.12.22.20.34.37
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Tue, 22 Dec 2020 20:34:37 -0800 (PST)
From: "Tzvetomir Stoyanov (VMware)" <tz.stoyanov@gmail.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH 6/6] trace-cmd library man pages: Read tracing instances from
 a trace file.
Date: Wed, 23 Dec 2020 06:34:29 +0200
Message-Id: <20201223043429.586162-7-tz.stoyanov@gmail.com>
X-Mailer: git-send-email 2.28.0
In-Reply-To: <20201223043429.586162-1-tz.stoyanov@gmail.com>
References: <20201223043429.586162-1-tz.stoyanov@gmail.com>
MIME-Version: 1.0
Precedence: bulk
List-ID: <linux-trace-devel.vger.kernel.org>
X-Mailing-List: linux-trace-devel@vger.kernel.org

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).