From patchwork Mon Dec 21 06:02:45 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984259 Return-Path: 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 3AC91C433E6 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 06D7822513 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727224AbgLUGD6 (ORCPT ); Mon, 21 Dec 2020 01:03:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49524 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727517AbgLUGD5 (ORCPT ); Mon, 21 Dec 2020 01:03:57 -0500 Received: from mail-ej1-x635.google.com (mail-ej1-x635.google.com [IPv6:2a00:1450:4864:20::635]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8D926C0611C5 for ; Sun, 20 Dec 2020 22:02:57 -0800 (PST) Received: by mail-ej1-x635.google.com with SMTP id b9so11856585ejy.0 for ; Sun, 20 Dec 2020 22:02:57 -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=TVOL8/VsCPrTv60SM2PZEO4mp5XV2QCtPhzzp2RC3yY=; b=HuTqMyIAaSfvGPR3IxfR8KQNwbeUeFfDZS+1nixpgCizuoXuR0wbulxKSIyt9AsN2E wpIMmK79bzHZ1E8IAbgX7RqE3AxFQZsa0q3W4lCJlMSneYbPEX8wQahQA9KRFNJzSPem H6Ak46PIzBQGYaIa3D2Ko0PzANr3gaHNMjB5BksamKHiTzlydttD84j66G1barO599rD Y4c1IqsjWf31Df72xRyMwLqqsKzYfrwJxWsgFEKvEqETPynmBnZazB60b7wnp+l1asSo VSRCKwACu8HjPlJlmdszQH79+bsRMi+0BgQcM9O2SlasJuV6Tys16cCia5YekgYHv0rs T28g== 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=TVOL8/VsCPrTv60SM2PZEO4mp5XV2QCtPhzzp2RC3yY=; b=KiHomEUZp8Oiyi+XhEOwrw28Q/MAMo7sdkMzHUz8pTkMBLz6E2I9tKQ8Gk8MeTuLh4 VrSfrrHA9UQzA6F5hNo8m1JjytRS4royTeY8NOqgzhqrcamzjgm7DMXD/hKTAihfN+dw sP+o2DvN1PyTAbbWmIBi9EIPJvKNMtnxD2DiJ+gRAtilkxJJX0S/vOuzsjmf4B4CcqRy /PDuJ2kIP7TfZjwSkAUBHRD4RX8l/977oEBa1omwDSNcUTFOremuhTOEEWwJp8Hw2Vgo CmqTqQn1TAim8lFpqGAMSr/TSahcvc18ArKcyCChZQiPidFTr2Ew6mahw761gOWyHEo7 chEQ== X-Gm-Message-State: AOAM533PZoOc7U/zuQsP1WNy3p83DnaViOz4CXJREvMiH8lh36Wq4315 nRilm81rHI/LSxFu2PewRKTdDtj000Rtd/sf X-Google-Smtp-Source: ABdhPJxkqtA1FwxkprU1Kzdq51ZxUF6Ur6iKKgjnxV/zIBCK24423+5pn4hQdx0BrZfNiZJt017OhA== X-Received: by 2002:a17:906:52c1:: with SMTP id w1mr1017454ejn.214.1608530576228; Sun, 20 Dec 2020 22:02:56 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.02.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:02:54 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 1/8] libtracefs: Initial support for man pages Date: Mon, 21 Dec 2020 08:02:45 +0200 Message-Id: <20201221060252.177890-2-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Basic infrastructure for libtracefs man pages and the first man page: man libtracefs with list of all library APIs. Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/Makefile | 211 +++++++++++++++++++++++++ Documentation/asciidoc.conf | 120 ++++++++++++++ Documentation/libtracefs.txt | 84 ++++++++++ Documentation/manpage-1.72.xsl | 14 ++ Documentation/manpage-base.xsl | 35 ++++ Documentation/manpage-bold-literal.xsl | 17 ++ Documentation/manpage-normal.xsl | 13 ++ Documentation/manpage-suppress-sp.xsl | 21 +++ 8 files changed, 515 insertions(+) create mode 100644 Documentation/Makefile create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/libtracefs.txt create mode 100644 Documentation/manpage-1.72.xsl create mode 100644 Documentation/manpage-base.xsl create mode 100644 Documentation/manpage-bold-literal.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/manpage-suppress-sp.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..e9212df --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,211 @@ +# SPDX-License-Identifier: LGPL-2.1 + +include $(src)/scripts/utils.mk + + +# This Makefile and manpage XSL files were taken from libtraceevent +# and modified for libtracefs. + +MAN3_TXT= \ + $(wildcard libtracefs-*.txt) \ + libtracefs.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtracefs-doc +pdfdir?=$(prefix)/share/doc/libtracefs-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -a mansource="libtracefs" -a manmanual="libtracefs Manual" +ASCIIDOC_HTML = xhtml5 +endif + +XMLTO=xmlto + +_tmp_tool_path := $(call get-executable,$(ASCIIDOC)) +ifeq ($(_tmp_tool_path),) + missing_tools = $(ASCIIDOC) +endif + +ifndef USE_ASCIIDOCTOR +_tmp_tool_path := $(call get-executable,$(XMLTO)) +ifeq ($(_tmp_tool_path),) + missing_tools += $(XMLTO) +endif +endif + +# +# For asciidoc ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# + +ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtracefs-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtracefs-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +DESTDIR ?= +DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))' + +export DESTDIR DESTDIR_SQ + +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifneq ($(V),1) + QUIET_ASCIIDOC = @echo ' ASCIIDOC '$@; + QUIET_XMLTO = @echo ' XMLTO '$@; + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) \ + echo ' SUBDIR ' $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: html man + +man: man3 +man3: $(DOC_MAN3) + +html: $(MAN_HTML) + +$(MAN_HTML) $(DOC_MAN3): asciidoc.conf + +install: install-man install-html + +check-man-tools: +ifdef missing_tools + $(error "You need to install $(missing_tools) for man pages") +endif + +do-install-man: man + $(call QUIET_INSTALL, Documentation-man) \ + $(INSTALL) -d -m 755 $(DESTDIR)$(man3dir); \ + $(INSTALL) -m 644 $(OUTPUT)*.3 $(DESTDIR)$(man3dir); + +install-man: check-man-tools man do-install-man + +do-install-html: html + $(call QUIET_INSTALL, Documentation-html) \ + $(INSTALL) -d -m 755 $(DESTDIR)$(htmldir); \ + $(INSTALL) -m 644 $(OUTPUT)*.html $(DESTDIR)$(htmldir); + +install-html: check-man-tools html do-install-html + +uninstall: uninstall-man uninstall-html + +uninstall-man: + $(call QUIET_UNINST, Documentation-man) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3)) + +uninstall-html: + $(call QUIET_UNINST, Documentation-html) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(htmldir)/,$(MAN_HTML)) + +ifdef missing_tools + DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed) +else + DO_INSTALL_MAN = do-install-man +endif + +CLEAN_FILES = \ + $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ + $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ + $(DOC_MAN3) *.3 + +clean: + $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES) + +ifdef USE_ASCIIDOCTOR +$(OUTPUT)%.3 : $(OUTPUT)%.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ +endif + +$(OUTPUT)%.3 : $(OUTPUT)%.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +$(OUTPUT)%.xml : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(MAN_HTML): $(OUTPUT)%.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \ + $(ASCIIDOC_EXTRA) -aperf_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 0000000..0759571 --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,120 @@ +## linktep: macro +# +# Usage: linktep:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show TEP link as: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinktep):(?P\S*?)\[(?P.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[linktep-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifndef::tep-asciidoc-no-roff[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +# v1.72 breaks with this because it replaces dots not in roff requests. +[listingblock] +{title} + +ifdef::doctype-manpage[] + .ft C +endif::doctype-manpage[] +| +ifdef::doctype-manpage[] + .ft +endif::doctype-manpage[] + +{title#} +endif::tep-asciidoc-no-roff[] + +ifdef::tep-asciidoc-no-roff[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::tep-asciidoc-no-roff[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +libtraceevent +{libtraceevent_version} +libtraceevent Manual + + + {manname1} + {manname2} + {manname3} + {manname4} + {manname5} + {manname6} + {manname7} + {manname8} + {manname9} + {manname10} + {manname11} + {manname12} + {manname13} + {manname14} + {manname15} + {manname16} + {manname17} + {manname18} + {manname19} + {manname20} + {manname21} + {manname22} + {manname23} + {manname24} + {manname25} + {manname26} + {manname27} + {manname28} + {manname29} + {manname30} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linktep-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt new file mode 100644 index 0000000..bd40f1f --- /dev/null +++ b/Documentation/libtracefs.txt @@ -0,0 +1,84 @@ +libtracefs(3) +============= + +NAME +---- +libtracefs - Linux kernel trace file system library + +SYNOPSIS +-------- +[verse] +-- +*#include * + +Locations of tracing files and directories: + char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_); + void *tracefs_put_tracing_file*(char pass:[*]_name_); + const char pass:[*]*tracefs_tracing_dir*(void); + +Trace instances: + struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_); + int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_); + void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_); + bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_); + bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); + bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); + char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_); + char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_); + char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_); + const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_; + bool *tracefs_instance_exists*(const char pass:[*]_name_); + +Trace events: + char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_); + char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_); + int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_); + struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_); + struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_); + int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_); + +Trace helper functions: + void *tracefs_list_free*(char pass:[*]pass:[*]_list_); + char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); + char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); +-- + +DESCRIPTION +----------- +The libtracefs(3) library provides APIs to access kernel trace file system. + +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_ +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl new file mode 100644 index 0000000..b4d315c --- /dev/null +++ b/Documentation/manpage-1.72.xsl @@ -0,0 +1,14 @@ + + + + + + +▓ +⌂ + + diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 0000000..a264fa6 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 0000000..608eb5d --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ + + + + + + + fB + + + fR + + + diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 0000000..a48f5b1 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + + diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 0000000..a63c763 --- /dev/null +++ b/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + From patchwork Mon Dec 21 06:02:46 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984251 Return-Path: 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 5B61DC433E9 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 307D522B2A for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727517AbgLUGD6 (ORCPT ); Mon, 21 Dec 2020 01:03:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49526 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727566AbgLUGD5 (ORCPT ); Mon, 21 Dec 2020 01:03:57 -0500 Received: from mail-ed1-x534.google.com (mail-ed1-x534.google.com [IPv6:2a00:1450:4864:20::534]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D0735C0611CA for ; Sun, 20 Dec 2020 22:02:58 -0800 (PST) Received: by mail-ed1-x534.google.com with SMTP id j16so8504392edr.0 for ; Sun, 20 Dec 2020 22:02:58 -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=JNU1XUFo7bjZBFqse0EpQDDMCTQQR1xGfjDNxFxj3eM=; b=IbFQPpcv/wch8GXXONbdKZmyboG8pegCSaUyJJSO0NBzm7DEgwcGdHWcUyXSguOlaG dC9tapfJSLmLBcP6GELGIRoExpqhIB+FVunHPpdJl3GNZJyl0FrT+vngnXHm7PyTn2Ux nXTlkbLesk94S8VX/dW5TV6qf8372jC2v94+zxwvVHt1b/265M2VLgyXCRftQY2vRmq1 C8A9ZxtLHAwRocYPqWIPLFQ/AiNGFjF+yAAjmCn4frmZ3Sg68ojqa/zQMy5/x071d+nk xfYJv0Wnr6H9nMDw0Fd8q7EyZ3MMunvI0HT6URsVhDXCBGyoO3dQWWOWDKReoxHQVAek 3l+g== 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=JNU1XUFo7bjZBFqse0EpQDDMCTQQR1xGfjDNxFxj3eM=; b=oE/07lIXgv8Rm9M3xHTHd/DZeI1Sxa+0q4/ULfw7HqYfPuzTZpKSjXMvIt/4o4F/MM eIX+70LQUREjHrijTWgU3fiC6xLb4AdfYQmejI9Qd66AqZyXyNhOD6e88VJis6osMOOA eV2t7E22U3R5VrONgVGMJCC2/y4kr/Cj1PhvQT7tlz/5+/90VQXof3dQTx7//jJKdxDA wmJGYJ66jE2mGrwPbTjQ2zC0V5m9/9w4o1r26S10GfPt1ojKQAtdsl+fqfcPY7DuG1+1 qHYvap8G4SI0NMOcT1W8PJ+jltaJ1Z+ar6zb1jBw/88AAVpT9kKFTYBch0KozkE79cnA 9PaQ== X-Gm-Message-State: AOAM53087aTI/94YrQB/YPKDABHf4ijej05CKzkh8eHLjzz0aGzE32ax kDVTsBYBwM8lt7AJyoc3DNQ= X-Google-Smtp-Source: ABdhPJxses2puSu0SaGcUI9yRahwdztjAhct4VYAR/iAQZcb9H0c4309VpueGcYZo9ozzjqZq5u7Lg== X-Received: by 2002:aa7:d608:: with SMTP id c8mr14405498edr.260.1608530577619; Sun, 20 Dec 2020 22:02:57 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.02.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:02:56 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files. Date: Mon, 21 Dec 2020 08:02:46 +0200 Message-Id: <20201221060252.177890-3-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_get_tracing_file() tracefs_put_tracing_file() tracefs_get_tracing_dir() tracefs_find_tracing_dir() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 Documentation/libtracefs-files.txt diff --git a/Documentation/libtracefs-files.txt b/Documentation/libtracefs-files.txt new file mode 100644 index 0000000..8bf9d75 --- /dev/null +++ b/Documentation/libtracefs-files.txt @@ -0,0 +1,97 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_tracing_dir - +Find locations of trace directory and files. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_); +void *tracefs_put_tracing_file*(char pass:[*]_name_); +const char pass:[*]*tracefs_tracing_dir*(void); +-- + +DESCRIPTION +----------- +This set of APIs can be used to find the full path of the trace file +system mount point and trace files in it. + +The _tracefs_get_tracing_file()_ function returns the full path of the +file with given _name_ in the trace file system. The function works +only with files in the trasefs main directory, it is not trace instance +aware. It is recommended to use _tracefs_instance_get_file()_ and +_tracefs_instance_get_dir()_ instead. The returned string must be freed +with _tracefs_put_tracing_file()_. + +The _tracefs_put_tracing_file()_ function frees trace file name, +returned by _tracefs_get_tracing_file()_. + +The _tracefs_tracing_dir()_ function returns the full path to the +trace file system. In the first function call, the mount point of the +tracing file system is located, cached and returned. It will mount it, +if it is not mounted. On any subsequent call the cached path is returned. +The return string must _not_ be freed. + +RETURN VALUE +------------ +The _tracefs_get_tracing_file()_ function returns a string or NULL in case +of an error. The returned string must be freed with _tracefs_put_tracing_file()_. + +The _tracefs_tracing_dir()_ function returns a constant string or NULL +in case of an error. The returned string must _not_ be freed. + +EXAMPLE +------- +[source,c] +-- +#include +... +char *trace_on = tracefs_get_tracing_file("tracing_on"); + if (trace_on) { + ... + tracefs_put_tracing_file(trace_on); + } +... +const char *trace_dir = tracefs_tracing_dir(); + +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:47 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984253 Return-Path: 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 7DC3AC43381 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 59A6222513 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727566AbgLUGD6 (ORCPT ); Mon, 21 Dec 2020 01:03:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49528 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727670AbgLUGD5 (ORCPT ); Mon, 21 Dec 2020 01:03:57 -0500 Received: from mail-ed1-x531.google.com (mail-ed1-x531.google.com [IPv6:2a00:1450:4864:20::531]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 29F57C0611CB for ; Sun, 20 Dec 2020 22:03:00 -0800 (PST) Received: by mail-ed1-x531.google.com with SMTP id c7so8456586edv.6 for ; Sun, 20 Dec 2020 22:03:00 -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=5GZNYh356HhEcIbSlefkqNxXutdLhcij5aCTg2yE2II=; b=OOu9G1N2Ngbo7GeJyj7bZ10neJjiIn1F4udsLj79TmDadjVsAB0ivDh1T6UL1gyiGZ 55iSwoWnqy58LU02bJcZuHafFW8ErVIvFkUuGMz1Ps4bnKRCSwep5fmoCQv/k5qV6V5e jQHNjmAjoYdwuqNsobnGO7OHKzs+BNpLKyWW7QDS8IkatyI0l79RKKEFIjAR2qXgTnt0 wsTBuwunIRdR2QbGvyApPh5pe3IXgQQ2Wdee8apfjEsEMR++kWP2rD3bPZ26Dk3ma/pw RpR0ZqNJFF+rlFnkOgyWnpc9QiQJxolVHc3rfvz64njdazV6MvZrDCgc7hnRM0r1jTjg O8dg== 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=5GZNYh356HhEcIbSlefkqNxXutdLhcij5aCTg2yE2II=; b=HT/glIEpWUnoADoomPyjLhwhx31BhvZTmeUp2AqzpaZDLCrQ86P8f/tfnpPGhwJzl4 kM2pu4/BI/COKlIJ5/oGhg5WbRMKTwx8qTTu5PnnHci7Ic3kuKsntBYXLLCm4pklqKtM kFGBbVDHogwcKJzwF5LYXz0x+uy0N28rxe61vK1/FYbGxe/AXk+EReJnWp1tZNxmj1VQ 1364w6gCv/tM89RFYF3D1nqqDciOtj5YEi+HL7y8o2Avjhcfn3eQbF1RI+k4MvWFgCFn B0W0sB4URbuKCGIdmeOdIHyyTaHVVd/mbic442yDW+h846hHB0Yw20L4l1ausiMbQk/j iGKw== X-Gm-Message-State: AOAM532GeI/rxqwqvvVMvuLfF1k68KwnYr+wVZteQaOiJqSGiCzXyEe4 wU/PDzVyZE3BTATxHhuOzS0= X-Google-Smtp-Source: ABdhPJyL4jkks0W5LxtMxW0vS0iwIw4ffjnz4Fn6OEalAXCTBYBsXjA5Oa5f9BqFRYUzjODLP4hzZQ== X-Received: by 2002:a05:6402:a45:: with SMTP id bt5mr14721203edb.130.1608530578840; Sun, 20 Dec 2020 22:02:58 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.02.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:02:58 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events. Date: Mon, 21 Dec 2020 08:02:47 +0200 Message-Id: <20201221060252.177890-4-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_event_systems() tracefs_system_events() tracefs_iterate_raw_events() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-events.txt | 143 ++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 Documentation/libtracefs-events.txt diff --git a/Documentation/libtracefs-events.txt b/Documentation/libtracefs-events.txt new file mode 100644 index 0000000..3a51055 --- /dev/null +++ b/Documentation/libtracefs-events.txt @@ -0,0 +1,143 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_event_systems, tracefs_system_events, tracefs_iterate_raw_events - +Work with trace systems and events. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_); +char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_); +int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_); + +-- + +DESCRIPTION +----------- +Trace systems and events related APIs. + +The _tracefs_event_systems()_ function returns array of strings with the +names of all registered trace systems, located in the given _tracing_dir_ +directory. This could be NULL or the location of the tracefs mount point +for the trace systems of the local machine, or it may be a path to a copy +of the tracefs directory from another machine. The last entry in the array +is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_system_events()_ function returns array of strings with the +names of all registered trace events for given trace system specified by +_system_, located in the given _tracing_dir_ directory. This could be NULL +or the location of the tracefs mount point for the trace systems of the +local machine, or it may be a path to a copy of the tracefs directory +from another machine. The last entry in the array as a NULL pointer. +The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_interate_raw_events()_ function will read the tracefs raw +data buffers and call the specified _callback_ function for every event it +encounters. An initialized _tep_ handler is required (See +_tracefs_local_events_(3)). If _instance_ is NULL, then the toplevel +tracefs buffer is used, otherwise the buffer for the corresponding +_instance_ is read. To filter only on a subset of CPUs, _cpus_ and +_cpu_size_ may be set to only call _callback_ with events that occurred on +the CPUs specified, otherwise if _cpus_ is NULL then the _callback_ +function will be called for all events, and _cpu_size_ is ignored. The +_callback_ function will be called with the following parameters: A +pointer to a struct tep_event that corresponds to the type of event the +record is; The record representing the event; The CPU that the event +occurred on; and a pointer to user specified _context_. If the _callback_ +returns non-zero, the iteration stops. + + +RETURN VALUE +------------ +The _tracefs_event_systems()_ and __tracefs_system_events()_ functions return +an array of strings. The last element in that array is a NULL pointer. The array +must be freed with _tracefs_list_free()_ API. In case of an error, NULL is returned. + +The _tracefs_iterate_raw_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include + +char **systems = tracefs_event_systems(NULL); + + if (systems) { + int i = 0; + /* Got registered trace systems from the top trace instance */ + while (systems[i]) { + char **events = tracefs_system_events(NULL, systems[i]); + if (events) { + /* Got registered events in system[i] from the top trace instance */ + int j = 0; + + while (events[j]) { + /* Got event[j] in system[i] from the top trace instance */ + j++; + } + tracefs_list_free(events); + } + i++; + } + tracefs_list_free(systems); + } +.... +static int records_walk(struct tep_event *tep, struct tep_record *record, int cpu, void *context) +{ + /* Got recorded event on cpu */ + return 0; +} +... +struct tep_event *tep = tracefs_local_events(NULL); + + if (!tep) { + /* Failed to initialise tep handler with local events */ + ... + } + if (tracefs_iterate_raw_events(tep, NULL, NULL, 0, records_walk, NULL) < 0) { + /* Error walking through the recorded raw events */ + } + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:48 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984255 Return-Path: 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 B9607C4332D for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8F0EA22513 for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727670AbgLUGD6 (ORCPT ); Mon, 21 Dec 2020 01:03:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49530 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727837AbgLUGD5 (ORCPT ); Mon, 21 Dec 2020 01:03:57 -0500 Received: from mail-ej1-x62e.google.com (mail-ej1-x62e.google.com [IPv6:2a00:1450:4864:20::62e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 65F93C0611CC for ; Sun, 20 Dec 2020 22:03:01 -0800 (PST) Received: by mail-ej1-x62e.google.com with SMTP id g20so11834465ejb.1 for ; Sun, 20 Dec 2020 22:03:01 -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=+A8+Hn7YDKykiwvd1w4P2UVCb0lnehfD8DN5Tp5AImQ=; b=f7GurZX/AyMvVbmdUMnNS+DpytEcA4Evbp3XDU+ZROD6Wp+l0dJBsp5jwVZdkJHeq7 XS9ZFXe2JGL0eBTeuOJ168drPL31R0lgCAIBvklCW6uL7ORhS6TyKkN9wJniFF3TRzHF oukSO3QtywoTuIRYzskLwfxIkXuD73aI5q6U7rQ3I47dB+uTkVo9ASNIZe36khAMqvLj 7h0opIbwGuJdWYaGzKOorrth+tpeqxF6MfI981PCK8/VmP6sEVjfnplUF3H4L/YGRN15 a5+0Btf8h/4aNU55W+MLZ7YFZJVyoTmF9iS7AxN22QTK+38hsSn8Y7qN2LgU26p1pg6A CDGA== 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=+A8+Hn7YDKykiwvd1w4P2UVCb0lnehfD8DN5Tp5AImQ=; b=LFgiPN39gM9ewjrO4nS6mUw2anSGhJjp8pBZoBL0NkzCk+1BrwymqPBMw6dhcW7Yql AmePYgwrVeppVd7EWfGiA5pm4nh/zwslH2zxqcDy6Ala8DRuBJO9KRS9hSYlwyvL7NEt mt5IQKqEbsJChwjOO9azueDmDlxhS70Y2LB4WgFGHVR2JzNPii566w2PtNBv8XlntB2f 5+2WJMRIRXNsWP8WKfvgzVnZsfLbbW5c6bxekCSTT6FU8Bk32HZ2I6n2+sixFa/cKdBg lHwUvcgYa1w7Aix+oeC4GIdoTf7znwgmoC7I0E8UydBtk6PAz3Q6IemodA75IUC2oiUT +tsw== X-Gm-Message-State: AOAM531R5D11M77ERvq6e61g2e054rd/tG7j+9LtKKtkHBdzQVxoupxd 1si5Y3djEJz80+ElQ6rt/8mDHBlPiI2XH16Z X-Google-Smtp-Source: ABdhPJyDI4l/wb1dP/cbUDsNT/QXpqTofndDiOyoYMhbyxyQKM98GQXY7TJ2RYWq64ht+tK1GII4Dg== X-Received: by 2002:a17:907:2071:: with SMTP id qp17mr14177068ejb.110.1608530580099; Sun, 20 Dec 2020 22:03:00 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.02.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:02:59 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances. Date: Mon, 21 Dec 2020 08:02:48 +0200 Message-Id: <20201221060252.177890-5-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_instance_create() tracefs_instance_destroy() tracefs_instance_free() tracefs_instance_is_new() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-instances-manage.txt | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 Documentation/libtracefs-instances-manage.txt diff --git a/Documentation/libtracefs-instances-manage.txt b/Documentation/libtracefs-instances-manage.txt new file mode 100644 index 0000000..aca2161 --- /dev/null +++ b/Documentation/libtracefs-instances-manage.txt @@ -0,0 +1,111 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free, +tracefs_instance_is_new - Manage trace instances. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_); +int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_); +void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_); +bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_); + +-- + +DESCRIPTION +----------- +This set of functions can be used to manage trace instances. A trace +instance is a sub buffer used by the Linux tracing system. Given a unique +name, the events enabled in an instance do not affect the main tracing +system, nor other instances, as events enabled in the main tracing system +or other instances do not affect the given instance. + +The _tracefs_instance_create()_ function allocates and initializes a new +tracefs_instance structure and returns it. If the instance does not yet +exist in the system, it will be created. + +The _tracefs_instance_destroy()_ frees the _instance_ structure, and will +also remove the trace instance from the system. + +The _tracefs_instance_free()_ function frees the tracefs_instance structure, +without removing the trace instance from the system. + +The _tracefs_instance_is_new()_ function checks if the given _instance_ is +newly created by _tracefs_instance_create()_, or it has been in the system +before that. + +RETURN VALUE +------------ +The _tracefs_instance_create()_ function returns a pointer to a newly allocated +tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or +_tracefs_instance_free()_. + +The _tracefs_instance_destroy()_ function returns -1 in case of an error, +or 0 otherwise. + +The _tracefs_instance_is_new()_ function returns true if the +_tracefs_instance_create() that allocated _instance_ also created the +trace instance in the system, or false if the trace instance already +existed in the system when _instance_ was allocated by +_tracefs_instance_create()_. + +EXAMPLE +------- +[source,c] +-- +#include + +struct tracefs_instance *inst = tracefs_instance_create("foo"); + if (!inst) { + /* Error creating a new trace instance */ + ... + } + + ... + + if (tracefs_instance_is_new(inst)) + tracefs_instance_destroy(inst); + else + tracefs_instance_free(inst); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:49 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984257 Return-Path: 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 DB3B7C4332B for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AEAC622B2D for ; Mon, 21 Dec 2020 06:03:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727837AbgLUGD6 (ORCPT ); Mon, 21 Dec 2020 01:03:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49532 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728050AbgLUGD5 (ORCPT ); Mon, 21 Dec 2020 01:03:57 -0500 Received: from mail-ed1-x52b.google.com (mail-ed1-x52b.google.com [IPv6:2a00:1450:4864:20::52b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E1BC3C0611CD for ; Sun, 20 Dec 2020 22:03:02 -0800 (PST) Received: by mail-ed1-x52b.google.com with SMTP id i24so8466038edj.8 for ; Sun, 20 Dec 2020 22:03:02 -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=KxK4jW156xLsSBmOYzmXTCWc9wZHIsV4UBpC0gCdWoQ=; b=Cp/QtCb3aYixgUoRk1n0JiO3O/v1p41mGeQ9DuI4ALwrzBZldD7BsEZGzb6EU+MOXF ytJAl5DpEC4GKDEjHmRvp2lcWIGqWrPeIrcETnkrK+8YQGJ+aUt/0nxiPNc/bJnZTLg1 9tX+BxMEEOI4M2kD6ddwD7AKng4de+bvPanl/hPrghGoWVr+sXw9LuYXu9VFI9eDZlCM lHcvE54wrKqfuNfYt4bEgoRD4mhH37VpGeBLhSAUrZC0FJV4oVRrtG+THr/dSq6TQml8 3VW29rdqGLC87LOjrt2ocW2w9ZLw2WTgTf/5nA6PSfv2/62CWnjfwEwfsJczDVcED791 gQ7g== 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=KxK4jW156xLsSBmOYzmXTCWc9wZHIsV4UBpC0gCdWoQ=; b=huiT13ykEHoGkQixSP4sGt2waATvJrZYiKgzrTJWEejGedQjdcsPmslX6djNe55PbO yM3hpe1eACgUS062siDMojoM53cbfydQRNgRfLTQh21OJuiYOjcFAy2l64ENIFzF8hUy JREm1pjjKWIi0HX5Zg++mMRJXa9XjnObFqmABSzYV29NssPGDt0sdHIHQGBlxNddGkal iM20wawE1vGY5qNBCsWmXhGlYfy5r15k+8lL+3icJFAtLKDZhOoLk/rcoNG5CtTzl1dw jT9O54Qc1ytn6QtaiCshDKToWbbA0JY9kx1HdAW91XjTsRKekqD/1g8INev6gVdzuVo1 XmGA== X-Gm-Message-State: AOAM532f+/Pt/xr4CTKqrZpRIDNZp4TpN40T0aVv/RLKV1d1sNfa+Dwi vXQBS408LW7cfFR77+EEYvUNy8tBg4QWl/pm X-Google-Smtp-Source: ABdhPJxHBP6Ifz+pEIHFg4jJQA/owawLZj6Hf6kstz6Dh0v8FfrwuDfTWh1UMlEsk+XuHmQRM2HOGw== X-Received: by 2002:aa7:d297:: with SMTP id w23mr14634300edq.374.1608530581628; Sun, 20 Dec 2020 22:03:01 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.03.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:03:00 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 5/8] libtracefs man pages: APIs for working with files in trace instances. Date: Mon, 21 Dec 2020 08:02:49 +0200 Message-Id: <20201221060252.177890-6-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_file_exists() tracefs_dir_exists() tracefs_instance_get_file() tracefs_instance_get_dir() tracefs_instance_file_write() tracefs_instance_file_read() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-instances-files.txt | 160 +++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 Documentation/libtracefs-instances-files.txt diff --git a/Documentation/libtracefs-instances-files.txt b/Documentation/libtracefs-instances-files.txt new file mode 100644 index 0000000..7f9d381 --- /dev/null +++ b/Documentation/libtracefs-instances-files.txt @@ -0,0 +1,160 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_file_exists, tracefs_dir_exists, tracefs_instance_get_file, +tracefs_instance_get_dir, tracefs_instance_file_write, +tracefs_instance_file_read - Work with files in tracing instances. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_); +char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_); +char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_); + +-- + +DESCRIPTION +----------- +This set of APIs can be used to work with trace files in all trace instances. +Each of these APIs take an _instance_ argument, that can be NULL to act +on the top level instance. Otherwise, it acts on an instance created with +*tracefs_insance_create*(3) + +The _tracefs_file_exists()_ function checks if a file with _name_ exists in _instance_. + +The _tracefs_dir_exists()_ function checks if a directory with _name_ exists in _instance_. + +The _tracefs_instance_get_file()_ function returns the full path of the file +with given _name_ in _instance_. Note, it does not check if the file exists in +the instance. + +The _tracefs_instance_get_dir()_ function returns the full path of the directory +with given _name_ in _instance_. Note, it does not check if the directory exists +in the instance. + +The _tracefs_instance_file_write()_ function writes a string _str_ in a _file_ from +the given _instance_, without the terminating NULL character. + +The _tracefs_instance_file_read()_ function reads the content of a _file_ from +the given _instance_. + +RETURN VALUE +------------ +The _tracefs_file_exists()_ and _tracefs_dir_exists()_ functions return true if the +file / directory exist in the given instance or false if it does not exist. + +The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions return +a string or NULL in case of an error. The returned string must be freed with +_tracefs_put_tracing_file()_. + +The _tracefs_instance_file_write()_ function returns the number of written bytes, +or -1 in case of an error. + +The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated +string, read from the file, or NULL in case of an error. The returned string must +be freed with free(). + +EXAMPLE +------- +[source,c] +-- +#include + +struct tracefs_instance *inst = tracefs_instance_create("foo"); + if (!inst) { + /* Error creating a new trace instance */ + ... + } + + if (tracefs_file_exists(inst,"trace_clock")) { + /* The instance foo supports trace clock */ + char *path, *clock; + int size; + + path = = tracefs_instance_get_file(inst, "trace_clock") + if (!path) { + /* Error getting the path to trace_clock file in instance foo */ + ... + } + ... + tracefs_put_tracing_file(path); + + clock = tracefs_instance_file_read(inst, "trace_clock", &size); + if (!clock) { + /* Failed to read trace_clock file in instance foo */ + ... + } + ... + free(clock); + + if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) { + /* Failed to set gloabl trace clock in instance foo */ + ... + } + } else { + /* The instance foo does not support trace clock */ + } + + if (tracefs_dir_exists(inst,"options")) { + /* The instance foo supports trace options */ + char *path = tracefs_instance_get_file(inst, "options"); + if (!path) { + /* Error getting the path to options directory in instance foo */ + ... + } + + tracefs_put_tracing_file(path); + } else { + /* The instance foo does not support trace options */ + } + + ... + + if (tracefs_instance_is_new(inst)) + tracefs_instance_destroy(inst); + else + tracefs_instance_free(inst); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:50 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984263 Return-Path: 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,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 8EFEAC433E0 for ; Mon, 21 Dec 2020 06:04:02 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6603D22513 for ; Mon, 21 Dec 2020 06:04:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728195AbgLUGEC (ORCPT ); Mon, 21 Dec 2020 01:04:02 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49546 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728128AbgLUGEC (ORCPT ); Mon, 21 Dec 2020 01:04:02 -0500 Received: from mail-ej1-x62a.google.com (mail-ej1-x62a.google.com [IPv6:2a00:1450:4864:20::62a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4647DC0611CE for ; Sun, 20 Dec 2020 22:03:04 -0800 (PST) Received: by mail-ej1-x62a.google.com with SMTP id ce23so11785889ejb.8 for ; Sun, 20 Dec 2020 22:03:04 -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=QsqMVQCfhuTivF9IcYxjxO3F76SUYIobWK4h1GVmQUA=; b=uDnLG3++V3HZ4KvrkmWLN9IXljxXlrO/I0XGF4UYpHzWHx9Kt+SFQn5GiowpiA9U8w 1T06mDKXScP/intS+PhcUzXYxY6P/LWfxPGvj6yKTarXmcxoSSNwSzpG0NaxWKb9n2qy RDUDXKQ6ExgXBYxyutjBeLN4BILGUiqKPv8dMJBBM1BviPF1ucj7Oihm42ZUKfv48Bz5 ZZkiuXzCOJKosy80Q9id2H1Jmj1rChhQsWdx69S1r1WXBVif1mWTi0QPobJmlW+zfT+b /Mcxygmn/09Ct45R7Gsfi8LDKAgkR9WA1Tve7dkblmkTR2dNd0a+pqf4XWbUpF91UC26 0PEw== 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=QsqMVQCfhuTivF9IcYxjxO3F76SUYIobWK4h1GVmQUA=; b=GWLiIFaC0Q38q06UDMCJ6LD7SazEJ2LPP8UeASCbuWMWSIvXQWXBWdC22CXQXY1tr5 6ksmfK2P0QTxkktLUQFIOFZev/RZIz35tLTuyyr2mK0mqp/AfU6MlACltZvOYjMASoQI NXUuEREa/H6De+KwTizl7b69vp4Qj7aH6JoFXCBYYxapnj4xwp1J+VTfzMGN3FWsX8rp 6zMyoA4ueBcqeNac8NypUEMNAvLNJJ/1Alf2akLz4ZSk/vxVoEWYxP+NcLGwQIfZEWCQ Szt6miko9cHlpCeVikWkGS4Cj3e/LUkVHdCFf4HdFzR0O6c1WKqK8lPbuRd+eP96SkgX eM+Q== X-Gm-Message-State: AOAM530WjUz4zPV03adZ5h1wUm245zQ3MSvg2XFLCXWUbkgr8QFSa+O0 1vh07DA3XR/IwcXhqjl4gRX7Qoej+ozvktyV X-Google-Smtp-Source: ABdhPJxqyh1SAAYkfBoDhsuXdshrAkR16ylV16jU3GGFGM7AK3lT5zFHiSNYuseVanu0TDR9/A9HFw== X-Received: by 2002:a17:906:168f:: with SMTP id s15mr13703268ejd.180.1608530583065; Sun, 20 Dec 2020 22:03:03 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.03.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:03:02 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 6/8] libtracefs man pages: helper APIs for working with trace instances. Date: Mon, 21 Dec 2020 08:02:50 +0200 Message-Id: <20201221060252.177890-7-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_instance_get_name() tracefs_instances_walk() tracefs_instance_exists() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-instances-utils.txt | 112 +++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 Documentation/libtracefs-instances-utils.txt diff --git a/Documentation/libtracefs-instances-utils.txt b/Documentation/libtracefs-instances-utils.txt new file mode 100644 index 0000000..aa5efbd --- /dev/null +++ b/Documentation/libtracefs-instances-utils.txt @@ -0,0 +1,112 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists - +Helper functions for working with tracing instances. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_; +bool *tracefs_instance_exists*(const char pass:[*]_name_); + +-- + +DESCRIPTION +----------- +Helper functions for working with trace instances. + +The _tracefs_instance_get_name()_ function returns the name of the given _instance_. +Note that the top instance has no name, the function returns NULL for it. + +The _tracefs_instances_walk()_ function walks through all configured tracing +instances in the system and calls _callback_ for each one of them. The _context_ +argument is passed to the _callback_, together with the instance name. If the +_callback_ returns non-zero, the iteration stops. Note, the _callback_ is not +called for the top top instance. + +The _tracefs_instance_exists()_ function checks if an instance with the given +_name_ exists in the system. + +RETURN VALUE +------------ +The _tracefs_instance_get_name()_ returns a string or NULL in case of the top +instance. The returned string must _not_ be freed. + +The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1 +if the iteration was stopped by the _callback_, or -1 in case of an error. + +The _tracefs_instance_exists()_ returns true if an instance with the given name +exists in the system or false otherwise. + +EXAMPLE +------- +[source,c] +-- +#include + +struct tracefs_instance *inst; +.... +char *name = tracefs_instance_get_name(inst); + + if(name) { + /* Got name of the instance */ + } + +... +static int instance_walk(char *name, void *context) +{ + /* Got instance with name */ + return 0; +} +... + if (tracefs_instances_walk(instance_walk, NULL) < 0) { + /* Error walking through the instances */ + } +... + if (tracefs_instance_exists("foo")) { + /* There is instance with name foo in the system */ + } else { + /* There is no instance with name foo in the system */ + } +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:51 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984265 Return-Path: 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 D359AC433E6 for ; Mon, 21 Dec 2020 06:04:02 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A95C422513 for ; Mon, 21 Dec 2020 06:04:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728128AbgLUGEC (ORCPT ); Mon, 21 Dec 2020 01:04:02 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49548 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728183AbgLUGEC (ORCPT ); Mon, 21 Dec 2020 01:04:02 -0500 Received: from mail-ej1-x635.google.com (mail-ej1-x635.google.com [IPv6:2a00:1450:4864:20::635]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 85C90C0611CF for ; Sun, 20 Dec 2020 22:03:05 -0800 (PST) Received: by mail-ej1-x635.google.com with SMTP id q22so11821695eja.2 for ; Sun, 20 Dec 2020 22:03:05 -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=UGI7x9XGf8QdyR8SMGBQIxUmxZG5OF3RDAyFwTys9vM=; b=GIS/eIUx7i/JAVzWDaGkZa+Wlj1Cq4VYZmbnsBnV7SOmmXo0BoBSVPiYo9t3de7GlW 5QMqC3Ma7p0ouC1MS/yOlmZtO66OmpDlqyDOjfiQ8nVi9m8dp0fUWbvz69dXt1/jpt1b D8hD1aw0ee1q2taIj4KPfHIaJ4Vtt+ZKUCv2yRJdUiFkOhzzYx+OCqnOqi8AqG0R137M zFgLUd9EDCwGvTAzULwnpO+XoDh6C3AneDaiF0ErQGhyszX0evAUIU1RYKqrmOYpfZwC nxy7RSDdgDuAW5yFosqrgJ/qpSVXWG1ZA7/ZuUCfmBlo3UT2EIFmqR40lyQcLKtT0+BE hWrg== 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=UGI7x9XGf8QdyR8SMGBQIxUmxZG5OF3RDAyFwTys9vM=; b=ofLSIzlgBl4JjxxAVWsJb+mfHTBgFbLN8yZ8781kKVi1gjkmlV392WcybMT29sq8WJ K6RdUm2OIMlKkiZINgN67gIIbQupGie/7h/j9i251eUBHKNm6NO1irW83ucfi6hJN4m+ ua5sq51i/J8QaMRZijw8HY9XRcuRH1ZKo2eiEhEmCwkHd1c4Ne9egqWEK9fFNK+IyJpE 1sgFKo9WhX8bawPHnisHo6RpVKWDTPBsSgfr0vXZ9z3/n21lHrwDWWAmuDH67QJWWIwL fRBvM6szhrRlONTOwCs4bCAyMio2zjYN7w14LYY7C5HNdUfhSoTtDixpy3jwduAh8CXu oMfA== X-Gm-Message-State: AOAM532l/37fXG5cOjf/GghMk96fUY8o/5uxfvR+Ym4KlKM7sZLB2rC0 uFlWgLXchhqD0qBqFI/3jgo= X-Google-Smtp-Source: ABdhPJxhC4a0lZ/13B2uhko3YWJocySrGMkQYPSqKFAoHN2YMhnM/YGeVHQ27XK5Snf+atNVQv9glw== X-Received: by 2002:a17:907:720e:: with SMTP id dr14mr13996188ejc.303.1608530584253; Sun, 20 Dec 2020 22:03:04 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.03.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:03:03 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system. Date: Mon, 21 Dec 2020 08:02:51 +0200 Message-Id: <20201221060252.177890-8-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_local_events() tracefs_local_events_system() tracefs_fill_local_events() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-events-tep.txt | 131 ++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 Documentation/libtracefs-events-tep.txt diff --git a/Documentation/libtracefs-events-tep.txt b/Documentation/libtracefs-events-tep.txt new file mode 100644 index 0000000..a01ce0e --- /dev/null +++ b/Documentation/libtracefs-events-tep.txt @@ -0,0 +1,131 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events - +Initialize a tep handler with trace events from the local system. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_); +struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_); +int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_); + +-- + +DESCRIPTION +----------- +Functions for initializing a tep handler with trace events from the local system. + +The _tracefs_local_events()_ function allocates a new _tep_ handler and +initializes it with events from all trace systems, located in the given +_tracing_dir_ directory. This could be NULL or tracefs mount point, for +trace events in top instance, or full path to a trace instance, for trace +events in that instance. + +The _tracefs_local_events_system()_ function allocates a new _tep_ handler +and initializes it with events from specified trace systems _sys_names_, +located in the given _tracing_dir_ directory. This could be NULL or tracefs +mount point, for trace events in top instance, or full path to a trace instance, +for trace events in that instance. The _sys_names_ argument is an array of +trace system names, that will be used for _tep_ handler initialization. +The last element in that array must be a NULL pointer. + +The _tracefs_fill_local_events()_ function initializes already allocated _tep_ +handler with events from all trace systems, located in the given _tracing_dir_ +directory. This could be NULL or tracefs mount point, for trace events in +the top instance, or full path to a trace instance, for trace events in that +instance. The _tep_ argument must be a pointer to already allocated tep +handler, that is going to be initialized. The _parsing_failures_ argument +could be NULL or a pointer to an integer, where the number of failures while +parsing the event files are returned. + +RETURN VALUE +------------ +The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions +return pointer to allocated and initialized _tep_ handler, or NULL in +case of an error. The returned _tep_ handler must be freed with _tep_free()_. + +The _tracefs_fill_local_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +#include + +struct tep_event *tep; +... + tep = tracefs_local_events(NULL); + if (!tep) { + /* Failed to initialise tep handler with local events from top instance */ + ... + } +... + tep_free(tep); +... + const char *systems[] = {"ftrace", "irq", NULL}; + tep = tracefs_local_events_system(NULL, systems); + if (!tep) { + /* Failed to initialise tep handler with local events from + * ftrace and irq systems in top instance. + */ + ... + } +... + tep_free(tep); +... + int parsing_failures; + tep = tep_alloc(); + if (!tep) { + /* Failed to allocate a tep handler */ + ... + } + if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) { + /* Failed to initialise tep handler with local events from top instance */ + } +... + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file From patchwork Mon Dec 21 06:02:52 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 11984267 Return-Path: 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 08535C433E0 for ; Mon, 21 Dec 2020 06:04:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D7A9A22513 for ; Mon, 21 Dec 2020 06:04:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728208AbgLUGEH (ORCPT ); Mon, 21 Dec 2020 01:04:07 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49498 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728183AbgLUGEF (ORCPT ); Mon, 21 Dec 2020 01:04:05 -0500 Received: from mail-ed1-x529.google.com (mail-ed1-x529.google.com [IPv6:2a00:1450:4864:20::529]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9D2CBC0611D0 for ; Sun, 20 Dec 2020 22:03:06 -0800 (PST) Received: by mail-ed1-x529.google.com with SMTP id u19so8489192edx.2 for ; Sun, 20 Dec 2020 22:03:06 -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=HUU1Jh6FSWY9JTBNdVV/FN25lvc1+FDVD1OMUo4JEl8=; b=L9ZkYIN3fJgNhRb+CxmLZYPFlducuSDv7RSKDE2SiHRACfUBC58RNGhOBxCG3605BI uj7Gvq9NCh4hEHkGpiRTLZgY1CZleuiVe6GZ4qFUJiYv3nxl6SrvOlb7RZg4BQNE+F5r /vRxMO5GytPUt0jj6vtP7pKGV6tgI4cMWT54QRN0m4/g/DLkIjnPuI3YZ+zCr0mX4CLO hauNLDTaY9IcfCfJb30qVdVTomxpG0dNwQUepFsMkiV0HwIqb35dacu/4Lq8ohfEmGVR iBdUN9z3sUIS7JSVZVcMW4cxmRuPiE3BsYlC0ZPvrYr6dBFEc1LttlweljslZj6ngDWb gQtg== 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=HUU1Jh6FSWY9JTBNdVV/FN25lvc1+FDVD1OMUo4JEl8=; b=Eq5/cPpbn04wxA8NVg1vPllZPbKnmF5EGVQ3U+tifQjdoE0Rq9B9yXBzq+uQMeF9H1 HG08j9FcB6pvg1kCgQ033wrCfcYHk4k6EYwSCQAqHhQV8pfi1vUYwSFWKnDP1EFYm2Qy HGqISks8diMcqi/fdLnGXnJu/U23jO1vXbIf9ZD1sGg1riWRh2Gk5+J5EN/mdTHMuQjW WTZ2rTnhdL3LU1MGbiRZbXNZpJNH4yEnlGZXXCrwQA8zRmsss67FZIfe4WlQpXT8bLgU 4IZ1voATdQwWfs8NDYRYMa0r4OiY7uhZLkDBOg/ruzZ2NCHTgQQ2aP/31VQb+eVYwELn cdnw== X-Gm-Message-State: AOAM531P7yWbbDCAPeBIBz2cVL52xEl0TX7phoAsI8mMOkE+d/42TKYe oIkcYeQQcoXi/C7EdvJV8rQ= X-Google-Smtp-Source: ABdhPJzhNSmsGBVJgzzhIbTqSVf0cgx4yZkI4+vzBF6SjCV8Ek4A6wrIoEIT3yfqzlglV5qAq45C7A== X-Received: by 2002:a05:6402:ca2:: with SMTP id cn2mr14581021edb.137.1608530585399; Sun, 20 Dec 2020 22:03:05 -0800 (PST) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id z10sm8560885ejl.30.2020.12.20.22.03.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Dec 2020 22:03:04 -0800 (PST) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system. Date: Mon, 21 Dec 2020 08:02:52 +0200 Message-Id: <20201221060252.177890-9-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201221060252.177890-1-tz.stoyanov@gmail.com> References: <20201221060252.177890-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Documented APIs: tracefs_tracers() tracefs_get_clock() tracefs_list_free() Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-utils.txt | 103 +++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Documentation/libtracefs-utils.txt diff --git a/Documentation/libtracefs-utils.txt b/Documentation/libtracefs-utils.txt new file mode 100644 index 0000000..86dd754 --- /dev/null +++ b/Documentation/libtracefs-utils.txt @@ -0,0 +1,103 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_tracers, tracefs_get_clock, tracefs_list_free - +Helper functions for working with trace file system. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); +char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); +void *tracefs_list_free*(char pass:[*]pass:[*]_list_); +-- + +DESCRIPTION +----------- +Various useful functions for working with trace file system. + +The _tracefs_tracers()_ function returns array of strings with the +names of supported tracer plugins, located in the given _tracing_dir_ directory. +This could be NULL or tracefs mount point, for trace systems in top instance, +or full path to a trace instance, for trace systems in that instance. +The last entry in the array as a NULL pointer. The array must +be freed with _tracefs_list_free()_ API. + +The _tracefs_get_clock()_ function returns name of the current trace clock, +used in the given _instance_. If _instance_ is NULL, the clock of the main +trace instance is returned. The returned string must be freed with free(). + +The _tracefs_list_free()_ function frees an array of strings, returned by +_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_ +APIs. + +RETURN VALUE +------------ +The _tracefs_tracers()_ returns array of strings. The last element in that +array is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. +In case of an error, NULL is returned. + +The _tracefs_get_clock()_ returns string, that must be freed with free(), or NULL +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include + +char **tracers = tracefs_tracers(NULL); + + if (tracers) { + /* Got tracer plugins from the top trace instance */ + ... + tracefs_list_free(tracers); + } +.... +char *clock = tracefs_get_clock(NULL); + + if (clock) { + /* Got current trace clock of the top trace instance */ + ... + free(clock); + } +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ \ No newline at end of file