From patchwork Fri Apr 12 13:37:42 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898321 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id F035414DB for ; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C740D28DD1 for ; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C541128ED8; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8B4A628ECC for ; Fri, 12 Apr 2019 13:38:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726894AbfDLNiR (ORCPT ); Fri, 12 Apr 2019 09:38:17 -0400 Received: from mail-wr1-f68.google.com ([209.85.221.68]:35670 "EHLO mail-wr1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726874AbfDLNiR (ORCPT ); Fri, 12 Apr 2019 09:38:17 -0400 Received: by mail-wr1-f68.google.com with SMTP id w1so12007755wrp.2 for ; Fri, 12 Apr 2019 06:38:14 -0700 (PDT) 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=Fgg6kwPSWquDg5Q94087rZGX3/mSJKYhyR6XPj7ztcw=; b=NYu7kn3XNmu4CoM3Zwx2VCibO9Yy9h6rsV+7lEdbBY8dBDZnxWcePBHmwgNtt7X6V8 e7bJlaCdOdebYMYyhS6SjgzFjwYLVz6q0idAKIfYtJ2KB9d5T6fwJxhgJTubxCJLJjkm LBdxNSOmS9dz+p0X5kOQygu6/KbiFOF9Nw+V69qTTIEWH7pl4bxmjqYZgAlLxz2GsLqR wZmA8jdSWJtuHR2z94US/5S888IRW/d7Oe78rr9l8wy8k7nSrN7DO/8Tb19J6nrNhSKL eJDoCDRmnFTCyRmaMJKY55zEHVqXeEZ8yTJr8lbgm7T6QssWp6gj1O9V2Xc4LB7lKdtN YxKg== X-Gm-Message-State: APjAAAXVeBD9i3a7Q3trAS8i1fAXpMvOln1tqeOnK8tDmpFJl4TO0bx2 hF6l19m70BQw0NYiA8VCXVAo2Ohu X-Google-Smtp-Source: APXvYqzod3VUKM8oD3jZdaFuS54P3l5vB4RFyqUsibWzmCGmMc/PiP6VoDWgFm+a7MGDWW3xVnIwng== X-Received: by 2002:a5d:458f:: with SMTP id p15mr35302918wrq.188.1555076293800; Fri, 12 Apr 2019 06:38:13 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.12 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:13 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 01/30] tools/lib/traceevent: Implement libtraceevent man pages Date: Fri, 12 Apr 2019 16:37:42 +0300 Message-Id: <20190412133811.15878-2-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Initial support for libtraceevent man pages - Documentation directory, templates, configurations, Makefiles. The first man page is also part of the patch - summary of the library and all its APIs. Building of the documentation is integrated into the libtraceevent build process, new targets are added to its Makefile: make help make doc make doc-clean make doc-install make doc-uninstall Signed-off-by: Tzvetomir Stoyanov --- tools/lib/traceevent/Documentation/Makefile | 208 ++++++++++++++++++ .../traceevent/Documentation/asciidoc.conf | 91 ++++++++ .../Documentation/libtraceevent.txt | 203 +++++++++++++++++ .../traceevent/Documentation/manpage-1.72.xsl | 14 ++ .../traceevent/Documentation/manpage-base.xsl | 35 +++ .../Documentation/manpage-bold-literal.xsl | 17 ++ .../Documentation/manpage-normal.xsl | 13 ++ .../Documentation/manpage-suppress-sp.xsl | 21 ++ tools/lib/traceevent/Makefile | 33 +++ 9 files changed, 635 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/Makefile create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl diff --git a/tools/lib/traceevent/Documentation/Makefile b/tools/lib/traceevent/Documentation/Makefile new file mode 100644 index 000000000000..680a9771067f --- /dev/null +++ b/tools/lib/traceevent/Documentation/Makefile @@ -0,0 +1,208 @@ +include ../../../scripts/Makefile.include +include ../../../scripts/utilities.mak + +# This Makefile and manpage XSL files were taken from tools/perf/Documentation +# and modified for libtraceevent. + +MAN3_TXT= \ + $(wildcard libtraceevent-*.txt) \ + libtraceevent.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/libtraceevent-doc +pdfdir?=$(prefix)/share/doc/libtraceevent-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="libtraceevent" -a manmanual="libtraceevent 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 libtraceevent-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 libtraceevent-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 + +# +# Please note that there is a minor bug in asciidoc. +# The version after 6.0.3 _will_ include the patch found here: +# http://marc.theaimsgroup.com/?l=libtraceevent&m=111558757202243&w=2 +# +# Until that version is released you may have to apply the patch +# yourself - yes, all 6 characters of it! +# +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 + +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 $(DOC_MAN3) $(DESTDIR)$(man3dir); + +install-man: check-man-tools man do-install-man + +uninstall: uninstall-man + +uninstall-man: + $(call QUIET_UNINST, Documentation-man) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3)) + + +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/tools/lib/traceevent/Documentation/asciidoc.conf b/tools/lib/traceevent/Documentation/asciidoc.conf new file mode 100644 index 000000000000..1b03c63fb73a --- /dev/null +++ b/tools/lib/traceevent/Documentation/asciidoc.conf @@ -0,0 +1,91 @@ +## 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} +trace-cmd +{libtraceevent_version} +trace-cmd Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linktep-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/tools/lib/traceevent/Documentation/libtraceevent.txt b/tools/lib/traceevent/Documentation/libtraceevent.txt new file mode 100644 index 000000000000..a148bfc229af --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent.txt @@ -0,0 +1,203 @@ +libtraceevent(3) +================ + +NAME +---- +libtraceevent - Linux kernel trace event library + +SYNOPSIS +-------- +[verse] +-- +*#include * + +Management of tep handler data structure and access of its members: + struct tep_handle pass:[*]*tep_alloc*(void); + void *tep_free*(struct tep_handle pass:[*]_tep_); + void *tep_ref*(struct tep_handle pass:[*]_tep_); + void *tep_unref*(struct tep_handle pass:[*]_tep_); + int *tep_ref_get*(struct tep_handle pass:[*]_tep_); + void *tep_set_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_); + void *tep_clear_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_); + bool *tep_test_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flags_); + int *tep_get_cpus*(struct tep_handle pass:[*]_tep_); + void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_); + int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_); + void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_); + int *tep_get_page_size*(struct tep_handle pass:[*]_tep_); + void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_); + bool *tep_is_latency_format*(struct tep_handle pass:[*]_tep_); + void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_); + int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_); + int *tep_get_header_timestamp_size*(struct tep_handle pass:[*]_tep_); + bool *tep_is_old_format*(struct tep_handle pass:[*]_tep_); + int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_); + +Register / unregister APIs: + int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_); + int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); + int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_); + int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_); + int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); + int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._); + int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_); + +Plugins management: + struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_); + void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_); + char pass:[*]pass:[*]*tep_plugin_list_options*(void); + void *tep_plugin_free_options_list*(char pass:[*]pass:[*]_list_); + int *tep_plugin_add_options*(const char pass:[*]_name_, struct tep_plugin_option pass:[*]_options_); + void *tep_plugin_remove_options*(struct tep_plugin_option pass:[*]_options_); + void *tep_print_plugins*(struct trace_seq pass:[*]_s_, const char pass:[*]_prefix_, const char pass:[*]_suffix_, const struct tep_plugin_list pass:[*]_list_); + +Event related APIs: + struct tep_event pass:[*]*tep_get_event*(struct tep_handle pass:[*]_tep_, int _index_); + struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_); + int *tep_get_events_count*(struct tep_handle pass:[*]_tep_); + struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_); + struct tep_event pass:[*]pass:[*]*tep_list_events_copy*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_); + +Event printing: + void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, bool _use_trace_clock_); + void *tep_print_event_data*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); + void *tep_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); + void *tep_print_event_task*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); + void *tep_print_event_time*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]record, bool _use_trace_clock_); + void *tep_set_print_raw*(struct tep_handle pass:[*]_tep_, int _print_raw_); + +Event finding: + struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_); + struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_); + struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_); + +Parsing of event files: + int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_); + enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); + enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); + +APIs related to fields from event's format files: + struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_); + struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_); + void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_); + int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); + int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); + int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); + int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_); + +Event fileds printing: + void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_); + void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_); + int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); + int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); + +Event fileds finding: + struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); + struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_); + struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); + +Functions resolver: + int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_); + void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_); + const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); + unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); + +Filter management: + struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_); + enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_); + enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_); + int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_); + int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_); + void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_); + void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_); + char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_); + int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_); + int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_); + int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_); + +Parsing various data from the records: + void *tep_data_latency_format*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_); + int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); + int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); + int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); + int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); + +Command and task related APIs: + const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_tep_, int _pid_); + struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); + int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); + int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); + bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_); + int *tep_cmdline_pid*(struct tep_handle pass:[*]_tep_, struct cmdline pass:[*]_cmdline_); + +Endian related APIs: + int *tep_is_bigendian*(void); + unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_); + bool *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_); + void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); + bool *tep_is_local_bigendian*(struct tep_handle pass:[*]_tep_); + void *tep_set_local_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); + +Trace sequences: +*#include * + void *trace_seq_init*(struct trace_seq pass:[*]_s_); + void *trace_seq_reset*(struct trace_seq pass:[*]_s_); + void *trace_seq_destroy*(struct trace_seq pass:[*]_s_); + int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, ...); + int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_); + int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_); + int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_); + void *trace_seq_terminate*(struct trace_seq pass:[*]_s_); + int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_); + int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_); +-- + +DESCRIPTION +----------- +The libtraceevent(3) library provides APIs to access kernel tracepoint events, +located in the debugfs file system under the tracing/events directory. + +ENVIRONMENT +----------- +[verse] +-- +TRACEEVENT_PLUGIN_DIR + Additional plugin directory. All shared object files, located in this directory will be loaded as traceevent plugins. +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences related APIs. + Trace sequences are used to allow a function to call several other functions + to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/manpage-1.72.xsl b/tools/lib/traceevent/Documentation/manpage-1.72.xsl new file mode 100644 index 000000000000..b4d315cb8c47 --- /dev/null +++ b/tools/lib/traceevent/Documentation/manpage-1.72.xsl @@ -0,0 +1,14 @@ + + + + + + +▓ +⌂ + + diff --git a/tools/lib/traceevent/Documentation/manpage-base.xsl b/tools/lib/traceevent/Documentation/manpage-base.xsl new file mode 100644 index 000000000000..a264fa616093 --- /dev/null +++ b/tools/lib/traceevent/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl b/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl new file mode 100644 index 000000000000..608eb5df6281 --- /dev/null +++ b/tools/lib/traceevent/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ + + + + + + + fB + + + fR + + + diff --git a/tools/lib/traceevent/Documentation/manpage-normal.xsl b/tools/lib/traceevent/Documentation/manpage-normal.xsl new file mode 100644 index 000000000000..a48f5b11f3dc --- /dev/null +++ b/tools/lib/traceevent/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + + diff --git a/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl b/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 000000000000..a63c7632a87d --- /dev/null +++ b/tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + diff --git a/tools/lib/traceevent/Makefile b/tools/lib/traceevent/Makefile index f65243137d6d..e73a0f2aea24 100644 --- a/tools/lib/traceevent/Makefile +++ b/tools/lib/traceevent/Makefile @@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \ export man_dir man_dir_SQ INSTALL export DESTDIR DESTDIR_SQ +export EVENT_PARSE_VERSION set_plugin_dir := 1 @@ -313,6 +314,38 @@ clean: $(RM) TRACEEVENT-CFLAGS tags TAGS; \ $(RM) $(PKG_CONFIG_FILE) +PHONY += doc +doc: + $(call descend,Documentation) + +PHONY += doc-clean +doc-clean: + $(call descend,Documentation,clean) + +PHONY += doc-install +doc-install: + $(call descend,Documentation,install) + +PHONY += doc-uninstall +doc-uninstall: + $(call descend,Documentation,uninstall) + +PHONY += help +help: + @echo 'Possible targets:' + @echo'' + @echo ' all - default, compile the library and the'\ + 'plugins' + @echo ' plugins - compile the plugins' + @echo ' install - install the library, the plugins,'\ + 'the header and pkgconfig files' + @echo ' clean - clean the library and the plugins object files' + @echo ' doc - compile the documentation files - man'\ + 'and html pages, in the Documentation directory' + @echo ' doc-clean - clean the documentation files' + @echo ' doc-install - install the man pages' + @echo ' doc-uninstall - uninstall the man pages' + @echo'' PHONY += force plugins force: From patchwork Fri Apr 12 13:37:43 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898315 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 703591515 for ; Fri, 12 Apr 2019 13:38:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 57FAF28EC7 for ; Fri, 12 Apr 2019 13:38:17 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 4C70628EC3; Fri, 12 Apr 2019 13:38:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DCF0F28B12 for ; Fri, 12 Apr 2019 13:38:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726826AbfDLNiQ (ORCPT ); Fri, 12 Apr 2019 09:38:16 -0400 Received: from mail-wr1-f65.google.com ([209.85.221.65]:39456 "EHLO mail-wr1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726884AbfDLNiQ (ORCPT ); Fri, 12 Apr 2019 09:38:16 -0400 Received: by mail-wr1-f65.google.com with SMTP id j9so12011264wrn.6 for ; Fri, 12 Apr 2019 06:38:15 -0700 (PDT) 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=ajjyB1oXnzRIg9g9v5mJwY6aetnydGPN6FUpkexlbTo=; b=dNiPl0bXDa1fFE1NVXqd5ehGb0HoR5YnQKtfEiC3KOJmMMTueqHNZb768iSolPaojD +aS70CWO6/HafJyzy1AHWxKHSb2equFItTb2ikoBXEfc1qSwP85txOJ8r7mkt39YXg86 j2PLQSibsOaoobbTHN0Vac6NyQKRp5Lzx4eolaXV+tVK4a4aF8ra6c0YVDEMq5Oe4eyJ mx2+vVu9oPOXUdWEG3mMVHXx4kulqKa8BpybiNHWf8eWmgpHfvIO9tTM1kXIMpIu8Ea3 nPgtHAmQ6Cl3UMWIJUbd25aNAmFbNFRd39VybYQPivzc+ApOxa6N9aObunO6MZi5ZUUf 0UXQ== X-Gm-Message-State: APjAAAWi3sutXx4DAUAf4iBWquz7OWF9kkpSetPZL5F0LBuDltY8IKXJ IHe/FoTSjNTCnztiXEAkvxXPfIw7 X-Google-Smtp-Source: APXvYqwvxT1uJCeQJoNQskFIoQ/4Uc0yAt5x9u5+csNdG+dewE1V4QK91GtYMbUnx5N5MBhZ/FUQUA== X-Received: by 2002:a5d:6a0b:: with SMTP id m11mr34887231wru.290.1555076294750; Fri, 12 Apr 2019 06:38:14 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.13 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:14 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 02/30] tools/lib/traceevent: Add support for man pages with multiple names Date: Fri, 12 Apr 2019 16:37:43 +0300 Message-Id: <20190412133811.15878-3-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Added support for man pages with multiple names, used to combine the description of several APIs into one page. Signed-off-by: Tzvetomir Stoyanov --- .../traceevent/Documentation/asciidoc.conf | 35 +++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/tools/lib/traceevent/Documentation/asciidoc.conf b/tools/lib/traceevent/Documentation/asciidoc.conf index 1b03c63fb73a..07595717f06e 100644 --- a/tools/lib/traceevent/Documentation/asciidoc.conf +++ b/tools/lib/traceevent/Documentation/asciidoc.conf @@ -74,12 +74,41 @@ template::[header-declarations] {mantitle} {manvolnum} -trace-cmd +libtraceevent {libtraceevent_version} -trace-cmd Manual +libtraceevent Manual - {manname} + {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[] From patchwork Fri Apr 12 13:37:44 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898323 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 35CED186E for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 19EF728DAA for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1823228ED7; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C38EC28DAA for ; Fri, 12 Apr 2019 13:38:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726765AbfDLNiS (ORCPT ); Fri, 12 Apr 2019 09:38:18 -0400 Received: from mail-wm1-f49.google.com ([209.85.128.49]:54305 "EHLO mail-wm1-f49.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726884AbfDLNiS (ORCPT ); Fri, 12 Apr 2019 09:38:18 -0400 Received: by mail-wm1-f49.google.com with SMTP id c1so11280858wml.4 for ; Fri, 12 Apr 2019 06:38:16 -0700 (PDT) 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=YzQG1BbHAMaQeWCmvso1h3ng5oVT0zP7vzV4w1Br6+Y=; b=PEtB6qp4zvtPvDq2790BHq9CAUWmTyQ7u5W/VkHrEUMRh0bNbGRi51h4jyGysRgXRS VWiakdpIZP1oATBdRnRe6/4d2G4ddjnlLhL/2NU+rDXZzz6QEYxl6jWk4WWRmjwj8GR4 d8H+cQhNCaOyqNZlc4zhGqupJhvZ0A7OpIIjJksd6lzwo86jgr27LEpyWycrPmTZdGYI Wgg98/x7KXkCYAqOhgvANmuzFFzQ8eDU0f50nu4QfE0dZpnpJeYyzwy1OqAnh5M0eh8g SxvFBoax0lpSPtEOEGO06YV+IfehHQlp2+3V7Bi9ymuIbbn+sayerEvUvDCPcOUdIpwF SjBA== X-Gm-Message-State: APjAAAWZH1k1lt8/Rpsz+uQkpNII4QW+SJSQm8tn6uZ68mUyu6P9yVIX gzDVY0BH4Hwco70rWr8T1MtRfrBv X-Google-Smtp-Source: APXvYqyP0ZjGmZE3xLpNuNGdEveaRvQbnzYYLEA7x6t8oXOp9RqGmekT667gDnhvPp/bAEsNupJWFA== X-Received: by 2002:a1c:f204:: with SMTP id s4mr11140129wmc.51.1555076295678; Fri, 12 Apr 2019 06:38:15 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.14 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:15 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 03/30] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Date: Fri, 12 Apr 2019 16:37:44 +0300 Message-Id: <20190412133811.15878-4-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Added 4 new man pages, describing libtraceevent APIs: tep_register_comm(), tep_override_comm(), tep_is_pid_registered(), tep_data_comm_from_pid(), tep_data_pid_from_comm(), tep_cmdline_pid(), tep_alloc(), tep_free(), tep_get_long_size(), tep_set_long_size(), tep_set_flag(), tep_clear_flag(), tep_test_flag() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-commands.txt | 153 ++++++++++++++++++ .../Documentation/libtraceevent-handle.txt | 101 ++++++++++++ .../Documentation/libtraceevent-long_size.txt | 78 +++++++++ .../Documentation/libtraceevent-set_flag.txt | 104 ++++++++++++ 4 files changed, 436 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-commands.txt b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt new file mode 100644 index 000000000000..bec552001f8e --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt @@ -0,0 +1,153 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_comm, tep_override_comm, tep_pid_is_registered, +tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid - +Manage pid to process name mappings. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); +int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); +bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_); +const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_); +struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); +int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_); +-- + +DESCRIPTION +----------- +These functions can be used to handle the mapping between pid and process name. +The library builds a cache of these mappings, which is used to display the name +of the process, instead of its pid. This information can be retrieved from +tracefs/saved_cmdlines file. + +The _tep_register_comm()_ function registers a _pid_ / process name mapping. +If a command with the same _pid_ is already registered, an error is returned. +The _pid_ argument is the process ID, the _comm_ argument is the process name, +_tep_ is the event context. The _comm_ is duplicated internally. + +The _tep_override_comm()_ function registers a _pid_ / process name mapping. +If a process with the same pid is already registered, the process name string is +udapted with the new one. The _pid_ argument is the process ID, the _comm_ +argument is the process name, _tep_ is the event context. The _comm_ is +duplicated internally. + +The _tep_is_pid_registered()_ function checks if a pid has a process name +mapping registered. The _pid_ argument is the process ID, _tep_ is the event +context. + +The _tep_data_comm_from_pid()_ function returns the process name for a given +pid. The _pid_ argument is the process ID, _tep_ is the event context. +The returned string should not be freed, but will be freed when the _tep_ +handler is closed. + +The _tep_data_pid_from_comm()_ function returns a pid for a given process name. +The _comm_ argument is the process name, _tep_ is the event context. +The argument _next_ is the cmdline structure to search for the next pid. +As there may be more than one pid for a given process, the result of this call +can be passed back into a recurring call in the _next_ parameter, to search for +the next pid. If _next_ is NULL, it will return the first pid associated with +the _comm_. The function performs a linear search, so it may be slow. + +The _tep_cmdline_pid()_ function returns the pid associated with a given +_cmdline_. The _tep_ argument is the event context. + +RETURN VALUE +------------ +_tep_register_comm()_ function returns 0 on success. In case of an error -1 is +returned and errno is set to indicate the cause of the problem: ENOMEM, if there +is not enough memory to duplicate the _comm_ or EEXIST if a mapping for this +_pid_ is already registered. + +_tep_override_comm()_ function returns 0 on success. In case of an error -1 is +returned and errno is set to indicate the cause of the problem: ENOMEM, if there +is not enough memory to duplicate the _comm_. + +_tep_is_pid_registered()_ function returns true if the _pid_ has a process name +mapped to it, false otherwise. + +_tep_data_comm_from_pid()_ function returns the process name as string, or the +string "<...>" if there is no mapping for the given pid. + +_tep_data_pid_from_comm()_ function returns a pointer to a struct cmdline, that +holds a pid for a given process, or NULL if none is found. This result can be +passed back into a recurring call as the _next_ parameter of the function. + +_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_ + is NULL, then -1 is returned. + +EXAMPLE +------- +The following example registers pid for command "ls", in context of event _tep_ +and performs various searches for pid / process name mappings: +[source,c] +-- +#include +... +int ret; +int ls_pid = 1021; +struct tep_handle *tep = tep_alloc(); +... + ret = tep_register_comm(tep, "ls", ls_pid); + if (ret != 0 && errno == EEXIST) + ret = tep_override_comm(tep, "ls", ls_pid); + if (ret != 0) { + /* Failed to register pid / command mapping */ + } +... + if (tep_is_pid_registered(tep, ls_pid) == 0) { + /* Command mapping for ls_pid is not registered */ + } +... + const char *comm = tep_data_comm_from_pid(tep, ls_pid); + if (comm) { + /* Found process name for ls_pid */ + } +... + int pid; + struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL); + while (cmd) { + pid = tep_cmdline_pid(tep, cmd); + /* Found pid for process "ls" */ + cmd = tep_data_pid_from_comm(tep, "ls", cmd); + } +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt new file mode 100644 index 000000000000..8d568316847d --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt @@ -0,0 +1,101 @@ +libtraceevent(3) +================ + +NAME +---- +tep_alloc, tep_free,tep_ref, tep_unref,tep_ref_get - Create, destroy, manage +references of trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_handle pass:[*]*tep_alloc*(void); +void *tep_free*(struct tep_handle pass:[*]_tep_); +void *tep_ref*(struct tep_handle pass:[*]_tep_); +void *tep_unref*(struct tep_handle pass:[*]_tep_); +int *tep_ref_get*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +These are the main functions to create and destroy tep_handle - the main +structure, representing the trace event parser context. This context is used as +the input parameter of most library APIs. + +The _tep_alloc()_ function allocates and initializes the tep context. + +The _tep_free()_ function will decrement the reference of the _tep_ handler. +When there is no more references, then it will free the handler, as well +as clean up all its resources that it had used. The argument _tep_ is +the pointer to the trace event parser context. + +The _tep_ref()_ function adds a reference to the _tep_ handler. + +The _tep_unref()_ function removes a reference from the _tep_ handler. When +the last reference is removed, the _tep_ is destroyed, and all resources that +it had used are cleaned up. + +The _tep_ref_get()_ functions gets the current references of the _tep_ handler. + +RETURN VALUE +------------ +_tep_alloc()_ returns a pointer to a newly created tep_handle structure. +NULL is returned in case there is not enough free memory to allocate it. + +_tep_ref_get()_ returns the current references of _tep_. +If _tep_ is NULL, 0 is returned. + +EXAMPLE +------- +[source,c] +-- +#include + +... +struct tep_handle *tep = tep_alloc(); +... +int ref = tep_ref_get(tep); +tep_ref(tep); +if ( (ref+1) != tep_ref_get(tep)) { + /* Something wrong happened, the counter is not incremented by 1 */ +} +tep_unref(tep); +... +tep_free(tep); +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt new file mode 100644 index 000000000000..01d78ea2519a --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_long_size, tep_set_long_size - Get / set the size of a long integer on +the machine, where the trace is generated, in bytes + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_); +void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_); +-- + +DESCRIPTION +----------- +The _tep_get_long_size()_ function returns the size of a long integer on the machine, +where the trace is generated. The _tep_ argument is trace event parser context. + +The _tep_set_long_size()_ function sets the size of a long integer on the machine, +where the trace is generated. The _tep_ argument is trace event parser context. +The _long_size_ is the size of a long integer, in bytes. + +RETURN VALUE +------------ +The _tep_get_long_size()_ function returns the size of a long integer on the machine, +where the trace is generated, in bytes. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +tep_set_long_size(tep, 4); +... +int long_size = tep_get_long_size(tep); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt new file mode 100644 index 000000000000..7e258086348e --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt @@ -0,0 +1,104 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_flag, tep_clear_flag, tep_test_flag - +Manage flags of trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_flag* { + _TEP_NSEC_OUTPUT_, + _TEP_DISABLE_SYS_PLUGINS_, + _TEP_DISABLE_PLUGINS_ +}; +void *tep_set_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_); +void *tep_clear_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_); +bool *tep_test_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_); +-- + +DESCRIPTION +----------- +Trace event parser context flags are defined in *enum tep_flag*: +[verse] +-- +_TEP_NSEC_OUTPUT_ - print event's timestamp in nano seconds, instead of micro seconds. +_TEP_DISABLE_SYS_PLUGINS_ - disable plugins, located in system's plugin + directory. This directory is defined at library compile + time, and usually depends on library installation + prefix: (install_preffix)/lib/traceevent/plugins +_TEP_DISABLE_PLUGINS_ - disable all library plugins: + - in system's plugin directory + - in directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ + - in user's home directory, _~/.traceevent/plugins_ +-- +Note: plugin related flags must me set before calling _tep_load_plugins()_ API. + +The _tep_set_flag()_ function sets _flag_ to _tep_ context. + +The _tep_clear_flag()_ function clears _flag_ from _tep_ context. + +The _tep_test_flag()_ function tests if _flag_ is set to _tep_ context. + +RETURN VALUE +------------ +_tep_test_flag()_ function returns true if _flag_ is set, false otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +/* Print timestamps in nanoseconds */ +tep_set_flag(tep, TEP_NSEC_OUTPUT); +... +if (tep_test_flag(tep, TEP_NSEC_OUTPUT)) { + /* print timestamps in nanoseconds */ +} else { + /* print timestamps in microseconds */ +} +... +/* Print timestamps in microseconds */ +tep_clear_flag(tep, TEP_NSEC_OUTPUT); +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:45 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898319 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 63FE21515 for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 485FA28D7F for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 472DC288BB; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 46EA428ED5 for ; Fri, 12 Apr 2019 13:38:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726921AbfDLNiS (ORCPT ); Fri, 12 Apr 2019 09:38:18 -0400 Received: from mail-wm1-f65.google.com ([209.85.128.65]:55454 "EHLO mail-wm1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726907AbfDLNiS (ORCPT ); Fri, 12 Apr 2019 09:38:18 -0400 Received: by mail-wm1-f65.google.com with SMTP id o25so11274359wmf.5 for ; Fri, 12 Apr 2019 06:38:17 -0700 (PDT) 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=FLXNULcmM8V+HAfXfH+q1nJkgQ2LtsvRkPzQ0znRZiU=; b=o2VTb0w5o3zTrQIgWTssnbaegZPYxW9e7M/MLYqtAj3qu+R9giq9A8eUsvZydJhe9v 4DqXBxCWtj/lJzl1PxJDBLIl9BZkJefjOAE9aR0GN7M6Q1UEHLrqD4oIWRZ2TeJTEqVP c241z127MnjedT+vyqXkInTvZRL9YwFlWYtQw675IDqHV3H4vhSrf1Yj4slenodYGhf7 igCtrUkY8Izc0QRiCunxDE12y6oI/UBUHIUDJBfoWKT8xV5xtFPgQXNoZ0Wrd/4o+fT0 wSgWThZ86RFD5iVFkqbaUvjgHyCaYH6BSq+Udw8J9bFVrOQ34BhPNt8kx59m69vLFSns EP5g== X-Gm-Message-State: APjAAAWvzldkoogtH5lPYcVNK7LpKSP6TK2fozmYVyu34tFKpsHYWY/7 0mjdQq+8tpe+3wGFOIt5kSg= X-Google-Smtp-Source: APXvYqwb30Syf225Lr9NOd5NWIMwYrS3CWTKQs52pMItMPf+YcJASBU2xmiKdJNHL+OIDlMjbmammw== X-Received: by 2002:a1c:c504:: with SMTP id v4mr11591509wmf.45.1555076296460; Fri, 12 Apr 2019 06:38:16 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.15 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:15 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 04/30] tools/lib/traceevent: Man page for header_page APIs Date: Fri, 12 Apr 2019 16:37:45 +0300 Message-Id: <20190412133811.15878-5-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create a man page for libtraceevent APIs: tep_get_header_page_size(), tep_get_header_timestamp_size(), tep_is_old_format() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-header_page.txt | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_page.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-header_page.txt b/tools/lib/traceevent/Documentation/libtraceevent-header_page.txt new file mode 100644 index 000000000000..e1bd664ac123 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-header_page.txt @@ -0,0 +1,105 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_header_page_size, tep_get_header_timestamp_size, tep_is_old_format - +Get the data stored in the header page, in kernel context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_); +int *tep_get_header_timestamp_size*(struct tep_handle pass:[*]_tep_); +bool *tep_is_old_format*(struct tep_handle pass:[*]_tep_); +-- +DESCRIPTION +----------- +These functions retrieve information from kernel context, stored in +/sys/kernel/debug/tracing/events/header_page. Old kernels do not have header +page info, so default values from user space context are used. + +The _tep_get_header_page_size()_ function returns the size of a long integer, +in kernel context. The _tep_ argument is trace event parser context. +This information is retrieved from /sys/kernel/debug/tracing/events/header_page, + "commit" field. + +The _tep_get_header_timestamp_size()_ function returns the size of timestamps, +in kernel context. The _tep_ argument is trace event parser context. +This information is retrieved from /sys/kernel/debug/tracing/events/header_page, + "timestamp" field. + +The _tep_is_old_format()_ function returns if the kernel is old one and has no +/sys/kernel/debug/tracing/events/header_page. + +RETURN VALUE +------------ +The _tep_get_header_page_size()_ function returns the size of a long integer, +in bytes. + +The _tep_get_header_timestamp_size()_ function returns the size of timestamps, +in bytes. + +The _tep_is_old_format()_ function returns true, if an old kernel is used to +generate the tracing data, which has no +/sys/kernel/debug/tracing/events/header_page. If the kernel is new, or _tep_ is +NULL, false is returned. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + int longsize; + int timesize; + bool old; + + longsize = tep_get_header_page_size(tep); + timesize = tep_get_header_timestamp_size(tep); + old = tep_is_old_format(tep); + + printf ("%s kernel is used to generate the tracing data.\n", + old?"Old":"New"); + printf("The size of a long integer is %d bytes.\n", longsize); + printf("The timestamps size is %d bytes.\n", timesize); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:46 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898325 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0BD7517E0 for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DDD57289C6 for ; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id DBE1128EEA; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 64167289C6 for ; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726907AbfDLNiT (ORCPT ); Fri, 12 Apr 2019 09:38:19 -0400 Received: from mail-wr1-f68.google.com ([209.85.221.68]:34260 "EHLO mail-wr1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNiT (ORCPT ); Fri, 12 Apr 2019 09:38:19 -0400 Received: by mail-wr1-f68.google.com with SMTP id p10so12034626wrq.1 for ; Fri, 12 Apr 2019 06:38:17 -0700 (PDT) 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=1KgDXdXVNQ5+zLav00nRVLOERuuQFC9ZZ+74zZDhbYU=; b=AZZ34CEMuCH+SrVFAg9an7L81SWU6vXw56QDElUt5LEcADi5NSSqPHfVU0AjDNPMQr QLOc5P4d13CryZ4Ik2xPYJQp2Rg/d7utRtiU1n0InxOoB7/vEGZ1B1ddIx4juUXzqgx+ FJ1u/XBe2a41GI0YVD4gvAJ62JfZcOuvMstR/WUwYakNCsaq7L7HQCRzbNTSFfl2PJ1E ZRwuukK6Jzao5BBiVzKmd7IO/TTt2f0PYhpQtjohw1mn3IWEoKvyB1IMw3gJPzMFfrAw vLqijm8hnRiW2yzyI7L/odSNfqZVY5NLz20cXvnVtrYOOSyfweMDrl0l34JcTOAlopYj AoZw== X-Gm-Message-State: APjAAAWVTKpsx9msB1J9PrwYCke+kG8FtTiPThKhVNsi+B5Ru+XYXeQW bIf9aNYn85TsH0QpVVik75U= X-Google-Smtp-Source: APXvYqySeY32/k9qAEJ/+flk2DlfZaQxy5w7cZK0YlR0MOE3KyR3BxTjONniZhn9FDIb7usHOXEjKQ== X-Received: by 2002:adf:fd86:: with SMTP id d6mr15739723wrr.15.1555076297305; Fri, 12 Apr 2019 06:38:17 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.16 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:16 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 05/30] tools/lib/traceevent: Man page for get/set cpus APIs Date: Fri, 12 Apr 2019 16:37:46 +0300 Message-Id: <20190412133811.15878-6-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_get_cpus(), tep_set_cpus() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-cpus.txt | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file mode 100644 index 000000000000..5ad70e43b752 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt @@ -0,0 +1,77 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_cpus, tep_set_cpus - Get / set the number of CPUs, which have a tracing +buffer representing it. Note, the buffer may be empty. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_cpus*(struct tep_handle pass:[*]_tep_); +void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_); +-- + +DESCRIPTION +----------- +The _tep_get_cpus()_ function gets the number of CPUs, which have a tracing +buffer representing it. The _tep_ argument is trace event parser context. + +The _tep_set_cpus()_ function sets the number of CPUs, which have a tracing +buffer representing it. The _tep_ argument is trace event parser context. +The _cpu_ argument is the number of CPUs with tracing data. + +RETURN VALUE +------------ +The _tep_get_cpus()_ functions returns the number of CPUs, which have tracing +data recorded. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_cpus(tep, 5); +... + printf("We have tracing data for %d CPUs", tep_get_cpus(tep)); +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:47 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898317 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 904E418B7 for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6D2F528B4B for ; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6B51628ECB; Fri, 12 Apr 2019 13:38:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id F1EBB28B4B for ; Fri, 12 Apr 2019 13:38:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726874AbfDLNiT (ORCPT ); Fri, 12 Apr 2019 09:38:19 -0400 Received: from mail-wr1-f67.google.com ([209.85.221.67]:43781 "EHLO mail-wr1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726884AbfDLNiT (ORCPT ); Fri, 12 Apr 2019 09:38:19 -0400 Received: by mail-wr1-f67.google.com with SMTP id k17so7336272wrx.10 for ; Fri, 12 Apr 2019 06:38:18 -0700 (PDT) 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=7bejhqSWNJ6yrsYhJqtY8KvJICS0zi1EcjABl3JOxyQ=; b=qmoB6W8GPXSBN++PZi/kkU81o95U9B8m5W5jjRx6Kn5XtjlVDlktOgTepu3LESlG1r wsRzcVLhGDztwW5uo6JkiZZcDOm9jjXi/Y86mNs6auNyVkb+P9ZW8Mw6W8h2tIPRclm4 ubLaXdaMNpFOSI95HX/F4kCFlqS9hYXCF7nTISYiFfqSeDYMAICU1YlNvGGJ5VzBWqb7 8ZMlgUPw/c8d/Bl7csn1tsQkRKQOnf+HTNRHkQhI1k0PBXQbrhwJNj5XX75XafX3Qkix 4OybBoLT1aAMBPUOVaQSOUj+G5D7puUfeHTamJbxvcBOfTmQ3LhcKFhHcnCb6R8vU/3J Q9lg== X-Gm-Message-State: APjAAAUoAlxo5zHEseUcyyl5QAEupCiefitPexOFAug9NF8ventBy2HT A4JsunnogctahraHl1UZygo= X-Google-Smtp-Source: APXvYqzzlxRxbjUM3KBSHoU4t3uHf+sAlqr1ncGvbMAckoLosMvld9TpsGVq9w8oC6m/kbKZ/AYKfg== X-Received: by 2002:adf:e288:: with SMTP id v8mr29978170wri.7.1555076298299; Fri, 12 Apr 2019 06:38:18 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.17 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:17 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 06/30] tools/lib/traceevent: Man page for file endian APIs Date: Fri, 12 Apr 2019 16:37:47 +0300 Message-Id: <20190412133811.15878-7-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_is_file_bigendian(), tep_set_file_bigendian() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-file_endian.txt | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file mode 100644 index 000000000000..f401ad311047 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt @@ -0,0 +1,91 @@ +libtraceevent(3) +================ + +NAME +---- +tep_is_file_bigendian, tep_set_file_bigendian - Get / set the endianness of the +raw data being accessed by the tep handler. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_endian* { + TEP_LITTLE_ENDIAN = 0, + TEP_BIG_ENDIAN +}; + +bool *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_); +void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); + +-- +DESCRIPTION +----------- +The _tep_is_file_bigendian()_ function gets the endianness of the raw data, +being accessed by the tep handler. The _tep_ argument is trace event parser +context. + +The _tep_set_file_bigendian()_ function sets the endianness of raw data being +accessed by the tep handler. The _tep_ argument is trace event parser context. +[verse] +-- +The _endian_ argument is the endianness: + _TEP_LITTLE_ENDIAN_ - the raw data is in little endian format, + _TEP_BIG_ENDIAN_ - the raw data is in big endian format. +-- +RETURN VALUE +------------ +The _tep_is_file_bigendian()_ function returns true if the data is in bigendian +format, false otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_file_bigendian(tep, TEP_LITTLE_ENDIAN); +... + if (tep_is_file_bigendian(tep)) { + /* The raw data is in big endian */ + } else { + /* The raw data is in little endian */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:48 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898327 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C65BB1874 for ; Fri, 12 Apr 2019 13:38:21 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id ACC9828B15 for ; Fri, 12 Apr 2019 13:38:21 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id AAFB228EC4; Fri, 12 Apr 2019 13:38:21 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3D44328ECB for ; Fri, 12 Apr 2019 13:38:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726884AbfDLNiV (ORCPT ); Fri, 12 Apr 2019 09:38:21 -0400 Received: from mail-wm1-f67.google.com ([209.85.128.67]:37898 "EHLO mail-wm1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNiU (ORCPT ); Fri, 12 Apr 2019 09:38:20 -0400 Received: by mail-wm1-f67.google.com with SMTP id w15so11075539wmc.3 for ; Fri, 12 Apr 2019 06:38:19 -0700 (PDT) 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=d/nqsdMEdZ+hM2DW9KKOLLVpaUa3YlbnoObP+HnQpj8=; b=Tcygi5cVAmpUaADExS4NGqxtd7QTF1yEg5XF++Hih/je/dtgUal+O/YiJzHIzcTZnX d71HsDxZbaB7pN29DWTsdegbT5BYhTOGZpUrFOU+v+gtNc9yvgwgs70EuvokmjHz86EW kNRVJxStAXk/nJmXocOzCpsbruz6Uhd/xrcRtplE6vijZ1vzRheC6WmNISGDH0W0VDAm uyAgKZKHArI5xjNzGTIKTIZvSeEXXKiSMZ2RV9B99bwMsokL6zOS+Jz08beGtHlwQjNC UoMQEQL6bXUhJE4Ay5VHbx9aqMlnIPHCZ8dKC8huNMe8er+8w0Jg/51ZOg0t14uyi2Gl NuVA== X-Gm-Message-State: APjAAAWin+/VAhdTDrTW2VG+8crYK4Olr1MNxzfj94Ph/n2814Kv9HLQ c8FiAFPafofunnU+XMKTKlQ= X-Google-Smtp-Source: APXvYqwTr5jbeo5NLqw89qcm8ZlwIOquNf388TbeBpqWwSAHpw9WkgEi+osnAOn1UT+DFCMoY8MO4Q== X-Received: by 2002:a1c:e709:: with SMTP id e9mr11722891wmh.14.1555076299214; Fri, 12 Apr 2019 06:38:19 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.18 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:18 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 07/30] tools/lib/traceevent: Man page for host endian APIs Date: Fri, 12 Apr 2019 16:37:48 +0300 Message-Id: <20190412133811.15878-8-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_is_bigendian(), tep_is_local_bigendian(), tep_set_local_bigendian() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-host_endian.txt | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file mode 100644 index 000000000000..f313d64c4e7e --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt @@ -0,0 +1,106 @@ +libtraceevent(3) +================ + +NAME +---- +tep_is_bigendian, tep_is_local_bigendian, tep_set_local_bigendian - Get / set +the endianness of the local machine. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_endian* { + TEP_LITTLE_ENDIAN = 0, + TEP_BIG_ENDIAN +}; + +int *tep_is_bigendian*(void); +bool *tep_is_local_bigendian*(struct tep_handle pass:[*]_tep_); +void *tep_set_local_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); +-- + +DESCRIPTION +----------- + +The _tep_is_bigendian()_ gets the endianness of the machine, executing +the function. + +The _tep_is_local_bigendian()_ function gets the endianness of the local +machine, saved in the _tep_ handler. The _tep_ argument is the trace event +parser context. + +The _tep_set_local_bigendian()_ function sets the endianness of the local +machine in the _tep_ handler. The _tep_ argument is trace event parser context. +The _endian_ argument is the endianness: +[verse] +-- + _TEP_LITTLE_ENDIAN_ - the machine is little endian, + _TEP_BIG_ENDIAN_ - the machine is big endian. +-- + +RETURN VALUE +------------ +The _tep_is_bigendian()_ function returns non zero if the endianness of the +machine, executing the code, is big endian and zero otherwise. + +The _tep_is_local_bigendian()_ function returns true, if the endianness of the +local machine, saved in the _tep_ handler, is big endian, or false otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN); +... + if (tep_is_local_bigendian(tep)) { + /* The stored local host endian is big */ + } else { + /* The stored local host endian is little */ + } +... + if (tep_is_bigendian()) { + /* The local host endian is big */ + } else { + /* The local host endian is little */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:49 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898329 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id E1D5C14DB for ; Fri, 12 Apr 2019 13:38:22 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C8BAB28EC2 for ; Fri, 12 Apr 2019 13:38:22 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C6C0228EDA; Fri, 12 Apr 2019 13:38:22 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1FC2728ED8 for ; Fri, 12 Apr 2019 13:38:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726930AbfDLNiW (ORCPT ); Fri, 12 Apr 2019 09:38:22 -0400 Received: from mail-wm1-f68.google.com ([209.85.128.68]:40646 "EHLO mail-wm1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726812AbfDLNiV (ORCPT ); Fri, 12 Apr 2019 09:38:21 -0400 Received: by mail-wm1-f68.google.com with SMTP id z24so11160129wmi.5 for ; Fri, 12 Apr 2019 06:38:20 -0700 (PDT) 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=WayPe/ynCqy+9hs7lwlZYmXZV7ePNTuMwn+lkelWKBQ=; b=EIEppgdM4YK3P+Fm9lmwuyB8FyZWWmaENa2Tj/SMiLK1w0ORcgZZLk2nJyYhLeZ5IN u3LLxH/MVRKSVZQfWzhL1iYo7x63uklJPXZoRzKXW0Tqiu4A/gMEHzHviJvS8bBuSxlK 8FmF3GouUg9PN4TSFRpzYE8ClE21qs8Pl297Tmq2Dzc/XqgaMwk0ddLo1QpA7MADojEC hUOl7R7cHKIyz5x0MPVGsjKNt+0MqyuU6vRdKm4YE738pYXoo9wzQho6nIrOOVBjgc6/ FjE1YYgXbsVO/t++IRl4vcMnZPQFCWx08x+7sHmoMa5sDTKhx1FzKS3WeVwzPsV/V+WA IDfg== X-Gm-Message-State: APjAAAURL9CXnBPe9n+D1UK2w4N40IcTkzguz0RowrWJrzniTaSzGkP9 UIcWbhFZdK9V7jDfhzqGdMJlvqhv X-Google-Smtp-Source: APXvYqzaeKQkIhDaNJmL/yWP4siGhZ4S5+cQ/OVJowZamIe/QNcvd/uUZxpE6iTMV8FYWfe3r6Us3A== X-Received: by 2002:a1c:415:: with SMTP id 21mr10770862wme.109.1555076300159; Fri, 12 Apr 2019 06:38:20 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.19 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:19 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 08/30] tools/lib/traceevent: Man page for page size APIs Date: Fri, 12 Apr 2019 16:37:49 +0300 Message-Id: <20190412133811.15878-9-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_get_page_size() tep_set_page_size() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-page_size.txt | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file mode 100644 index 000000000000..2496b2cb2980 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt @@ -0,0 +1,80 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_page_size, tep_set_page_size - Get / set the size of a memory page on +the machine, where the trace is generated + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_page_size*(struct tep_handle pass:[*]_tep_); +void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_); +-- + +DESCRIPTION +----------- +The _tep_get_page_size()_ function returns the size of a memory page on +the machine, where the trace is generated. The _tep_ argument is trace +event parser context. + +The _tep_set_page_size()_ function stores in the _tep_ context the size of a +memory page on the machine, where the trace is generated. +The _tep_ argument is trace event parser context. +The _page_size_ argument is the size of a memory page, in bytes. + +RETURN VALUE +------------ +The _tep_get_page_size()_ function returns size of the memory page, in bytes. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + int page_size = 4096; + tep_set_page_size(tep, page_size); + if ( 4096 != tep_get_page_size(tep)) { + /* Something wrong happened, page size is not set as expected */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:50 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898331 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0831714DB for ; Fri, 12 Apr 2019 13:38:25 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DE85428B44 for ; Fri, 12 Apr 2019 13:38:24 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id DCCFA28E11; Fri, 12 Apr 2019 13:38:24 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DBF6F28ED8 for ; Fri, 12 Apr 2019 13:38:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726968AbfDLNiW (ORCPT ); Fri, 12 Apr 2019 09:38:22 -0400 Received: from mail-wr1-f67.google.com ([209.85.221.67]:36794 "EHLO mail-wr1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNiW (ORCPT ); Fri, 12 Apr 2019 09:38:22 -0400 Received: by mail-wr1-f67.google.com with SMTP id y13so12038721wrd.3 for ; Fri, 12 Apr 2019 06:38:21 -0700 (PDT) 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=EgOzSQgupW8jx8Y3CtIHNk89ioZzbxqg1rnCSF3TTxE=; b=mYQWpHIYyE3EaMadIrcPs2HneiEZ/fA5K6VlirgYjHGSH+UgK4A+QAfnwNWk89Rs+p XA6Nv8uUMcYbtJ/KHwx9Xsq8vnrVFa/y1wchfI9Rqv8QXiBZnlMD8lATTtlIbUj1/Zgb LQmbP8zqRHB//h3ES7UQCz/advX1Roybqzd3jvWhw+TQ73Kpj7URHqvfOxLDotF2P0Zi A7HUKMuzRlmlw1wjFbfnMllcZPUqIn0bf0boTTHFwdBmgItQ1iHL5ayG8+mdv3yw4rFh RGwQ7aadfUyTxrQFbzetIVOtTa3FvJICf/jWV29aeUkTnKE61I1rdsElnRxfWlMHCtcV ZY7g== X-Gm-Message-State: APjAAAVYeQKKgE3N+wt2rRLGG2393TMW//VVwv5mToStADS3rYrP4Xyw aC5WEFjDES1lYMWSknLyFqXcHlFf X-Google-Smtp-Source: APXvYqydu3vmnPKLQFxapF5u2sOo9MvnbsCkKnyrBlJ5wE83J9amFCce5bW61B6+UmIKvnzUmm0ssg== X-Received: by 2002:adf:ed8a:: with SMTP id c10mr28958742wro.40.1555076300953; Fri, 12 Apr 2019 06:38:20 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.20 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:20 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 09/30] tools/lib/traceevent: Man page for tep_strerror() Date: Fri, 12 Apr 2019 16:37:50 +0300 Message-Id: <20190412133811.15878-10-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for tep_strerror() libtraceevent API. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-strerror.txt | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt new file mode 100644 index 000000000000..b3d625d01a8d --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt @@ -0,0 +1,80 @@ +libtraceevent(3) +================ + +NAME +---- +tep_strerror - Returns a string describing regular errno and tep error number. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_); + +-- +DESCRIPTION +----------- +The _tep_strerror()_ function converts tep error number into a human +readable string. +The _tep_ argument is trace event parser context. The _errnum_ is a regular +errno, defined in errno.h, or a tep error number. The string, describing this +error number is copied in the _buf_ argument. The _buflen_ argument is +the size of the _buf_. + +RETURN VALUE +------------ +The _tep_strerror()_ function returns 0, if a valid _errnum_ is passed and the +string is copied into _buf_. If _errnum_ is not a valid error number, +-1 is returned and _buf_ is not modified. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char buf[32]; +char *pool = calloc(1, 128); +if (tep == NULL) { + tep_strerror(tep, TEP_ERRNO__MEM_ALLOC_FAILED, buf, 32); + printf ("The pool is not initialized, %s", buf); +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:51 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898335 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 4ED5B186E for ; Fri, 12 Apr 2019 13:38:25 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2E14E28E13 for ; Fri, 12 Apr 2019 13:38:25 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2C2BE28EC8; Fri, 12 Apr 2019 13:38:25 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A1B22289C6 for ; Fri, 12 Apr 2019 13:38:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726997AbfDLNiY (ORCPT ); Fri, 12 Apr 2019 09:38:24 -0400 Received: from mail-wm1-f66.google.com ([209.85.128.66]:37902 "EHLO mail-wm1-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726812AbfDLNiY (ORCPT ); Fri, 12 Apr 2019 09:38:24 -0400 Received: by mail-wm1-f66.google.com with SMTP id w15so11075703wmc.3 for ; Fri, 12 Apr 2019 06:38:22 -0700 (PDT) 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=bUDFP96y6t0zBr12uIbr8NfufuZQqY5ZLq9u27ZVetg=; b=StDSyfHw3t0cO/lJ7phY+BiGvaF6o3hEOg1aY5AdGQRmG3pTFFjMqXM4DCtQAmLMWJ ujOLE3oEffv523wKNpyiR+46nE/jp6tb3g5RJb4ccoPyTPGHOFSKejRLcqsvYl2MXV/+ fYEOOCzK79fLaEfMbYb0nSDfnfT+bGpX1w7eW8FibXJb0yaGNQ6ee2lAqeulbBhAsSXc yAwRCWqNijpc6gu4eiu4Lte9xVpLYT7+a/lgwrmshVxCEGaoK+NDpiqfXUAbp9OSXTTx toe/mSxHV3etCDbDStmSi6YOXDI+tTZG76yHG7G6p1RkLB3q/JyXTg8syFfGhQAHOFAb UQlQ== X-Gm-Message-State: APjAAAU3I9HXDZZYyypzsfdCAz2qLiPDaw8oKN6dsWEUtvaGDAxF6sJy /TeHn9Tw9Iw3B6W013fsXlU= X-Google-Smtp-Source: APXvYqwwjOhLpWt7bI1GjK3ryZOJyVRIvNDlBVJp2rydLhNIjfzQY+DCsTnvBrS7BYmaoZWcchnKDg== X-Received: by 2002:a1c:9c03:: with SMTP id f3mr11591006wme.67.1555076301928; Fri, 12 Apr 2019 06:38:21 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.20 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:21 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 10/30] tools/lib/traceevent: Man page for tep_register_trace_clock() Date: Fri, 12 Apr 2019 16:37:51 +0300 Message-Id: <20190412133811.15878-11-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for tep_register_trace_clock() libtraceevent API. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-reg_clock.txt | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt new file mode 100644 index 000000000000..8bf6c5348fcf --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt @@ -0,0 +1,77 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_trace_clock - Registers the clock, used for the timestamp of +the events. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_); +-- + +DESCRIPTION +----------- +The _tep_register_trace_clock()_ function registers the clock, used for +the timestamps of the events. When an event is recorded, a timestamp is attached +to it. This timestamp comes from a specified clock. Supported clocks can be seen +in tracefs/trace_clock, the selected one is in square brackets. +The _tep_ argument is the trace event parser context. The _trace_clock_ argument +is the name of the clock, the string is copied internally. + +RETURN VALUE +------------ +The _tep_register_trace_clock()_ function returns 0 in case of success. +If there is not enough memory to copy the _trace_clock_ string -1 is returned +and errno is set to ENOMEM. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + if(tep_register_trace_clock(tep, "local") != 0) { + /* Failed to register the clock */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:52 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898337 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 8E1D417E0 for ; Fri, 12 Apr 2019 13:38:26 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6E73628A62 for ; Fri, 12 Apr 2019 13:38:26 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6CA9D28EC3; Fri, 12 Apr 2019 13:38:26 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AF82A28ECB for ; Fri, 12 Apr 2019 13:38:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727001AbfDLNiZ (ORCPT ); Fri, 12 Apr 2019 09:38:25 -0400 Received: from mail-wm1-f67.google.com ([209.85.128.67]:51516 "EHLO mail-wm1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNiZ (ORCPT ); Fri, 12 Apr 2019 09:38:25 -0400 Received: by mail-wm1-f67.google.com with SMTP id 4so11293286wmf.1 for ; Fri, 12 Apr 2019 06:38:23 -0700 (PDT) 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=KPUtG962/fGhN5OS1oN5GTAfFGa8nl96r76qp/aieDg=; b=NKm0W48D7Fsownk5gLKvX7FhmthBTGS1S8V+xGphnOEJj53YZI2D97JFDxO7FPZAk3 tV+u7DamMevueXKcMdNyfmBSPwRveNh4vPpz26ol/njU4XFa9G6iCFM3imVYqZDs/iHC KeRjCjOVcwDLZd7i9pDFPhW4hjfwP4qrqNwErGET0vNt8Jfy2JdAl6n0CtIO/AZR2Upx hXRb5ewShsFeb/lKtfVDMO1y10oPjCJmpDh8fIWBrpJJAUhg5Oo37cXooQtI5T6I7Bnd R/PXM8Wf3Fv7m1sxvpZQIx1DySt4d+S1oD6tYlcBD2jccpC4jh5Oi4XHe31SZxHTv9lg xKsw== X-Gm-Message-State: APjAAAU5ZvmD8rsgT9QCOkL+vrAwvFc+FqI+1kHQVuV1YLXBLrN4cIer UPzTHa2F9XvLjrrHqdxhcaQ= X-Google-Smtp-Source: APXvYqwmt7d3AwHtVcdwXrAmKLGDfWI6YChNe9bgGKktHtNtR2dqq7xjy/m+uqvEDoQNbH9vyQM9Xg== X-Received: by 2002:a7b:c5c7:: with SMTP id n7mr1735920wmk.9.1555076302739; Fri, 12 Apr 2019 06:38:22 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.21 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:22 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 11/30] tools/lib/traceevent: Man pages for event handler APIs Date: Fri, 12 Apr 2019 16:37:52 +0300 Message-Id: <20190412133811.15878-12-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_register_event_handler() tep_unregister_event_handler() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-reg_event_handler.txt | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt new file mode 100644 index 000000000000..8b1b75da7628 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt @@ -0,0 +1,131 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_event_handler, tep_unregister_event_handler - Register / +unregisters a callback function to parse an event information. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_reg_handler* { + _TEP_REGISTER_SUCCESS_, + _TEP_REGISTER_SUCCESS_OVERWRITE_, +}; + +int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_); +int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_); + +typedef int (*pass:[*]tep_event_handler_func*)(struct trace_seq pass:[*]s, struct tep_record pass:[*]record, struct tep_event pass:[*]event, void pass:[*]context); +-- + +DESCRIPTION +----------- +The _tep_register_event_handler()_ function registers a handler function, +which is going to be called to parse the information for a given event. +The _tep_ argument is the trace event parser context. The _id_ argument is +the id of the event. The _sys_name_ argument is the name of the system, +the event belongs to. The _event_name_ argument is the name of the event. +If _id_ is >= 0, it is used to find the event, otherwise _sys_name_ and +_event_name_ are used. The _func_ is a pointer to the function, which is going +to be called to parse the event information. The _context_ argument is a pointer +to the context data, which will be passed to the _func_. If a handler function +for the same event is already registered, it will be overridden with the new +one. This mechanism allows a developer to override the parsing of a given event. +If for some reason the default print format is not sufficient, the developer +can register a function for an event to be used to parse the data instead. + +The _tep_unregister_event_handler()_ function unregisters the handler function, +previously registered with _tep_register_event_handler()_. The _tep_ argument +is the trace event parser context. The _id_, _sys_name_, _event_name_, _func_, +and _context_ are the same arguments, as when the callback function _func_ was +registered. + +The _tep_event_handler_func_ is the type of the custom event handler +function. The _s_ argument is the trace sequence, it can be used to create a +custom string, describing the event. A _record_ to get the event from is passed +as input parameter and also the _event_ - the handle to the record's event. The +_context_ is custom context, set when the custom event handler is registered. + +RETURN VALUE +------------ +The _tep_register_event_handler()_ function returns _TEP_REGISTER_SUCCESS_ +if the new handler is registered successfully or +_TEP_REGISTER_SUCCESS_OVERWRITE_ if an existing handler is overwritten. +If there is not enough memory to complete the registration, +TEP_ERRNO__MEM_ALLOC_FAILED is returned. + +The _tep_unregister_event_handler()_ function returns 0 if _func_ was removed +successful or, -1 if the event was not found. + +The _tep_event_handler_func_ should return -1 in case of an error, +or 0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +int custom_event_handler(struct trace_seq *s, struct tep_record *record, + struct tep_event *event, void *context) +{ + trace_seq_printf(s, "kvm_exit event"); + return 0; +} +... + if (tep_register_event_handler(tep, -1, "kvm", "kvm_exit", + custom_event_handler, NULL)) { + /* Failed to register the handler for event "kvm_exit", "kvm" system */ + } +... + if (tep_unregister_event_handler(pevent, -1, "kvm", "kvm_exit", + custom_event_handler, NULL) != ) { + /* Failed to unregister the handler for event "kvm_exit", "kvm" system */ + } + +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences + related APIs. Trace sequences are used to allow a function to call + several other functions to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:53 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898339 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 3D5891515 for ; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1AF8328ED7 for ; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1908128DFB; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0DF4928DFB for ; Fri, 12 Apr 2019 13:38:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726931AbfDLNi0 (ORCPT ); Fri, 12 Apr 2019 09:38:26 -0400 Received: from mail-wr1-f67.google.com ([209.85.221.67]:40957 "EHLO mail-wr1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726812AbfDLNi0 (ORCPT ); Fri, 12 Apr 2019 09:38:26 -0400 Received: by mail-wr1-f67.google.com with SMTP id h4so11996818wre.7 for ; Fri, 12 Apr 2019 06:38:24 -0700 (PDT) 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=TEQRP+KtBxRKk/AMzsiVbqKj+oCAwixtWhG5cChb8ak=; b=cilJMeayYXRYhP/psaGbOL2SLjYvXzIxRMu3BFk+z8I/GakJnH4AcJX4ERiJCfcYtc uTQYeG+gSIdfW4STTBjq2IXiAhQ9xbyEaobsxauWPXbMhKt8PJ1r9loRFuJuww5E1wUw 8Z8MnVwVs81A2fYDHV/s5fGOEwcm4hXZkwKFXxwQOru4TqGRACfg2ENS/MWKpqmKDlNs Rz7YdjZXs6hJv47UuDirHUNCZCCZyFitHIdVmSDeuasrw9e1noI83r6sZQHn1Q5PvUkI pFmrVvyTjcTtreCqHh3Sk2iFy+wLHo6V6EjybL8p9k7nzsqe9hsa1SqZqe0DlTjZBbpt Bt6A== X-Gm-Message-State: APjAAAVj7YioqdNswnzdVYsO4bx6uBoo/riOVGTrINg+7cB3X1to4laQ LNNxyMxuBG43U4pZfkeZcl0= X-Google-Smtp-Source: APXvYqy+Zho2Ji4rh2XepZHsSArdZejK+GuqBx71qYgDTyULEapRjB/csnVEWkQxjvFsPYzsvcl7dQ== X-Received: by 2002:a5d:6646:: with SMTP id f6mr13406546wrw.68.1555076303707; Fri, 12 Apr 2019 06:38:23 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.22 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:23 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 12/30] tools/lib/traceevent: Man pages for function related libtraceevent APIs Date: Fri, 12 Apr 2019 16:37:53 +0300 Message-Id: <20190412133811.15878-13-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Added new man pages, describing function related libtraceevent APIs: tep_register_function(), tep_register_print_string(), tep_find_function(), tep_find_function_address(), tep_set_function_resolver(), tep_reset_function_resolver() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-func_apis.txt | 175 ++++++++++++++++++ .../Documentation/libtraceevent-func_find.txt | 88 +++++++++ 2 files changed, 263 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_apis.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_apis.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_apis.txt new file mode 100644 index 000000000000..1f69b472602e --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-func_apis.txt @@ -0,0 +1,175 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_function, tep_find_function_address, tep_set_function_resolver, +tep_reset_function_resolver, tep_register_function, tep_register_print_string - +function related tep APIs + +SYNOPSIS +-------- +[verse] +-- +*#include * + +typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_); +int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_); +void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_); +const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); +int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); +-- + +DESCRIPTION +----------- +Some tools may have already a way to resolve the kernel functions. These APIs +allow them to keep using it instead of duplicating all the entries inside. + +The _tep_func_resolver_t_ type is the prototype of the alternative kernel +functions resolver. This function receives a pointer to its custom context +(set with the _tep_set_function_resolver()_ call ) and the address of a kernel +function, which has to be resolved. In case of success, it should return +the name of the function and its module (if any) in _modp_. + +The _tep_set_function_resolver()_ function registers _func_ as an alternative +kernel functions resolver. The _tep_ argument is trace event parser context. +The _priv_ argument is a custom context of the _func_ function. The function +resolver is used by the APIs _tep_find_function()_, +_tep_find_function_address()_, and _tep_print_func_field()_ to resolve +a function address to a function name. + +The _tep_reset_function_resolver()_ function resets the kernel functions +resolver to the default function. The _tep_ argument is trace event parser +context. + + +These APIs can be used to find function name and start address, by given +address. The given address does not have to be exact, it will select +the function that would contain it. + +The _tep_find_function()_ function returns the function name, which contains the +given address _addr_. The _tep_ argument is the trace event parser context. + +The _tep_find_function_address()_ function returns the function start address, +by given address _addr_. The _addr_ does not have to be exact, it will select +the function that would contain it. The _tep_ argument is the trace event +parser context. + +The _tep_register_function()_ function registers a function name mapped to an +address and (optional) module. This mapping is used in case the function tracer +or events have "%pF" or "%pS" parameter in its format string. It is common to +pass in the kallsyms function names with their corresponding addresses with this +function. The _tep_ argument is the trace event parser context. The _name_ is +the name of the function, the string is copied internally. The _addr_ is +the start address of the function. The _mod_ is the kernel module +the function may be in (NULL for none). + +The _tep_register_print_string()_ function registers a string by the address +it was stored in the kernel. Some strings internal to the kernel with static +address are passed to certain events. The "%s" in the event's format field +which has an address needs to know what string would be at that address. The +tep_register_print_string() supplies the parsing with the mapping between kernel +addresses and those strings. The _tep_ argument is the trace event parser +context. The _fmt_ is the string to register, it is copied internally. +The _addr_ is the address the string was located at. + + +RETURN VALUE +------------ +The _tep_set_function_resolver()_ function returns 0 in case of success, or -1 +in case of an error. + +The _tep_find_function()_ function returns the function name, or NULL in case +it cannot be found. + +The _tep_find_function_address()_ function returns the function start address, +or 0 in case it cannot be found. + +The _tep_register_function()_ function returns 0 in case of success. In case of +an error -1 is returned, and errno is set to the appropriate error number. + +The _tep_register_print_string()_ function returns 0 in case of success. In case +of an error -1 is returned, and errno is set to the appropriate error number. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *my_resolve_kernel_addr(void *context, + unsigned long long *addrp, char **modp) +{ + return NULL; +} + +void show_function( unsigned long long addr) +{ + unsigned long long fstart; + const char *fname; + + if (tep_set_function_resolver(tep, my_resolve_kernel_addr, NULL) != 0) { + /* failed to register my_resolve_kernel_addr */ + } + + /* These APIs use my_resolve_kernel_addr() to resolve the addr */ + fname = tep_find_function(tep, addr); + fstart = tep_find_function_address(tep, addr); + + /* + addr is in function named fname, starting at fstart address, + at offset (addr - fstart) + */ + + tep_reset_function_resolver(tep); + +} +... + if (tep_register_function(tep, "kernel_function_foo", + (unsigned long long) 0x12345678, NULL) != 0) { + /* Failed to register kernel_function_foo address mapping */ + } +... + if (tep_register_print_string(tep, "print string", + (unsigned long long) 0x87654321, NULL) != 0) { + /* Failed to register "print string" address mapping */ + } +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt new file mode 100644 index 000000000000..04840e244445 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt @@ -0,0 +1,88 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_function,tep_find_function_address - Find function name / start address. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +-- + +DESCRIPTION +----------- +These functions can be used to find function name and start address, by given +address. The given address does not have to be exact, it will select the function +that would contain it. + +The _tep_find_function()_ function returns the function name, which contains the +given address _addr_. The _tep_ argument is the trace event parser context. + +The _tep_find_function_address()_ function returns the function start address, +by given address _addr_. The _addr_ does not have to be exact, it will select the +function that would contain it. The _tep_ argument is the trace event parser context. + +RETURN VALUE +------------ +The _tep_find_function()_ function returns the function name, or NULL in case +it cannot be found. + +The _tep_find_function_address()_ function returns the function start address, +or 0 in case it cannot be found. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void show_function( unsigned long long addr) +{ + const char *fname = tep_find_function(tep, addr); + unsigned long long fstart = tep_find_function_address(tep, addr); + + /* addr is in function named fname, starting at fstart address, at offset (addr - fstart) */ +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898341 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id A33B414DB for ; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8317728DAA for ; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8138828D11; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 55E5228EDA for ; Fri, 12 Apr 2019 13:38:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726812AbfDLNi1 (ORCPT ); Fri, 12 Apr 2019 09:38:27 -0400 Received: from mail-wm1-f65.google.com ([209.85.128.65]:52613 "EHLO mail-wm1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726998AbfDLNi1 (ORCPT ); Fri, 12 Apr 2019 09:38:27 -0400 Received: by mail-wm1-f65.google.com with SMTP id a184so11295269wma.2 for ; Fri, 12 Apr 2019 06:38:25 -0700 (PDT) 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=CY1D/yN46Y8efOfIDfVfmxQVFib2qqsDhe066xRSLHQ=; b=C8mmD7UJ9W4P2kd4biFzp7w1VCn7IlEnR5SpkOcNnqfzroElJEjn8/rKtINiwPm8iI TYhc429pEpe4/HPRhpUBcu6X5Sh5Kreb9Bty7YA5CbNgoaPtVONRfmxt+cHKfkF0U62Q wVEQPehUERL4VJ0XJBQlJvnZL8M1Ta47Y5AIl4j+DPN4Uf2CzMIq3svydcgzRfuiACRZ e8pYvhUcy6f83a8YfgLXYeiAWxlTi3xM1w6/A1WkfVSBix6yJ6v4qIoZyHY9/UCTXtl2 x1RtPkHJsuOd0OMZIuV+RTAvKZEWRyT6PEQg28egm+McEHz1VbWMhzybZKn5l9UhB4ra Xsfw== X-Gm-Message-State: APjAAAVJp4eNiiXacD1YfklovDp5UrVEDPQRbC2mfPSp41U7Mpu/LZ8M uTZ5TybI4pZxIhCr0t52WoQ= X-Google-Smtp-Source: APXvYqwQSkU2JpuOEmvzxcXow6WPXcD/iM5kGOiNw77pd/WEDVAwJ7DtZUnU42js+/NpcXx0aEt3Ow== X-Received: by 2002:a7b:c00e:: with SMTP id c14mr11663189wmb.110.1555076304615; Fri, 12 Apr 2019 06:38:24 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.23 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:23 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 13/30] tools/lib/traceevent: Man pages for registering print function Date: Fri, 12 Apr 2019 16:37:54 +0300 Message-Id: <20190412133811.15878-14-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_register_print_function() tep_unregister_print_function() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-reg_print_func.txt | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt new file mode 100644 index 000000000000..d95e0b19e4ca --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt @@ -0,0 +1,155 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_print_function,tep_unregister_print_function - +Registers / Unregisters a helper function. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_func_arg_type* { + TEP_FUNC_ARG_VOID, + TEP_FUNC_ARG_INT, + TEP_FUNC_ARG_LONG, + TEP_FUNC_ARG_STRING, + TEP_FUNC_ARG_PTR, + TEP_FUNC_ARG_MAX_TYPES +}; + +typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args); + +int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._); +int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_); +-- + +DESCRIPTION +----------- +Some events may have helper functions in the print format arguments. +This allows a plugin to dynamically create a way to process one of +these functions. + +The _tep_register_print_function()_ registers such helper function. The _tep_ +argument is the trace event parser context. The _func_ argument is a pointer +to the helper function. The _ret_type_ argument is the return type of the +helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name +of the helper function, as seen in the print format arguments. The _..._ is a +variable list of _tep_func_arg_type_ enums, the _func_ function arguments. +This list must end with _TEP_FUNC_ARG_VOID_. See 'EXAMPLE' section. + +The _tep_unregister_print_function()_ unregisters a helper function, previously +registered with _tep_register_print_function()_. The _tep_ argument is the +trace event parser context. The _func_ and _name_ arguments are the same, used +when the helper function was registered. + +The _tep_func_handler_ is the type of the helper function. The _s_ argument is +the trace sequence, it can be used to create a custom string. +The _args_ is a list of arguments, defined when the helper function was +registered. + +RETURN VALUE +------------ +The _tep_register_print_function()_ function returns 0 in case of success. +In case of an error, TEP_ERRNO_... code is returned. + +The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in +case of an error. + +EXAMPLE +------- +Some events have internal functions calls, that appear in the print format +output. For example "tracefs/events/i915/g4x_wm/format" has: +[source,c] +-- +print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s", + ((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary, + REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane, + REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane, + REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc) +-- +Notice the call to function _yesno()_ in the print arguments. In the kernel +context, this function has the following implementation: +[source,c] +-- +static const char *yesno(int x) +{ + static const char *yes = "yes"; + static const char *no = "no"; + + return x ? yes : no; +} +-- +The user space event parser has no idea how to handle this _yesno()_ function. +The _tep_register_print_function()_ API can be used to register an user space +helper function, mapped to the kernel's _yesno()_: +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +static const char *yes_no_helper(int x) +{ + return x ? "yes" : "no"; +} +... + if ( tep_register_print_function(tep, + yes_no_helper, + TEP_FUNC_ARG_STRING, + "yesno", + TEP_FUNC_ARG_INT, + TEP_FUNC_ARG_VOID) != 0) { + /* Failed to register yes_no_helper function */ + } + +/* + Now, when the event parser encounters this yesno() function, it will know + how to handle it. +*/ +... + if (tep_unregister_print_function(tep, yes_no_helper, "yesno") != 0) { + /* Failed to unregister yes_no_helper function */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences + related APIs. Trace sequences are used to allow a function to call + several other functions to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:55 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898345 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D06A817E0 for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B6DDE28B44 for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id B4E7928EC3; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C256928B44 for ; Fri, 12 Apr 2019 13:38:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727015AbfDLNi1 (ORCPT ); Fri, 12 Apr 2019 09:38:27 -0400 Received: from mail-wm1-f67.google.com ([209.85.128.67]:40659 "EHLO mail-wm1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNi1 (ORCPT ); Fri, 12 Apr 2019 09:38:27 -0400 Received: by mail-wm1-f67.google.com with SMTP id z24so11160537wmi.5 for ; Fri, 12 Apr 2019 06:38:26 -0700 (PDT) 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=e4zoqIUhc24m0lhZmvGFYfefxJEB4lfbL7L7QxrfiEg=; b=kpt7NAKe2DzfWY/b/hNUVacrFfWAMtfv4Djx5bszKa6vnSUwg21vJF37O84m+rohjF Phaee1buCPUrZbrNwZzwxkxliyvij9yA1M7+Z7nO5CCYbw76Hmk1bCvwpV12UqHiN0Q9 fFbg8bM6LqYs8X00CI7KtWjCreaMbK0+uXO8J/WZwvyRVZn/DVWmNR7dARUNGfIs6N94 ahdBF9hdoe7rH7aJWcwExjQezfyvRk53BL86m4Nia1mmz3JcK3wiVPy8S9nM47D+m8WU FfyJ42sV27ENgkpv+heI2eFVMR+ojYNE01PdAmIXrjrkktNje80Lqi8kz2oKY74kc6l8 SsiA== X-Gm-Message-State: APjAAAVzpWCAM4mtG8K20LmfENcaPSCClLR4WHpVMIx6QcNcicfjhjfu byFTMc8SzAgYIQ/kkqpPY1U= X-Google-Smtp-Source: APXvYqz8dR7WNWDcGWU05MmhM0vN4oVySotJL8Q7wlPXDOPvJ0tIvvf7YWtGaNxy8vcizjggk3GP1A== X-Received: by 2002:a1c:7d42:: with SMTP id y63mr11220007wmc.113.1555076305556; Fri, 12 Apr 2019 06:38:25 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.24 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:24 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 14/30] tools/lib/traceevent: Man page for tep_read_number() Date: Fri, 12 Apr 2019 16:37:55 +0300 Message-Id: <20190412133811.15878-15-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for tep_read_number() libtraceevent API. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-endian_read.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt new file mode 100644 index 000000000000..e64851b6e189 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_read_number - Reads a number from raw data. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_); +-- + +DESCRIPTION +----------- +The _tep_read_number()_ function reads an integer from raw data, taking into +account the endianness of the raw data and the current host. The _tep_ argument +is the trace event parser context. The _ptr_ is a pointer to the raw data, where +the integer is, and the _size_ is the size of the integer. + +RETURN VALUE +------------ +The _tep_read_number()_ function returns the integer in the byte order of +the current host. In case of an error, 0 is returned. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void process_record(struct tep_record *record) +{ + int offset = 24; + int data = tep_read_number(tep, record->data + offset, 4); + + /* Read the 4 bytes at the offset 24 of data as an integer */ +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:56 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898343 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 3BD61186E for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1CE2126247 for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1B33628EDC; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9ADB728EC8 for ; Fri, 12 Apr 2019 13:38:28 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726951AbfDLNi2 (ORCPT ); Fri, 12 Apr 2019 09:38:28 -0400 Received: from mail-wr1-f65.google.com ([209.85.221.65]:40959 "EHLO mail-wr1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727006AbfDLNi2 (ORCPT ); Fri, 12 Apr 2019 09:38:28 -0400 Received: by mail-wr1-f65.google.com with SMTP id h4so11997038wre.7 for ; Fri, 12 Apr 2019 06:38:27 -0700 (PDT) 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=R5c6X1sPM/DT/aUqxJe5D5K5sUaoWjAY02jCdIwH8H4=; b=KRvyLMi2YG8GuFYBggz7rtQ9EOnvO621Xi/YDN2KuT40dd8p/X0bZ8218TG6AC7Dgx rkAGC6sNGMqB32l8dT3FARDOI0HPdg0rGYvy9aqaRs8T2s7etSousDM9kqmBPay5L2Ou 55jMA/wbtWqgwXCGdiTXehywHV8FE7dZKp82ShL0FOr/p4l1zsatw8TBmsDzva1p/7FB qKzQXjm5af+V3ilnpgnxcp119Sudk9kWLsrm9b5LEmINYBRC5Iu40REKLtyPokdbKzWi XoucuIFuVjdFE2z4FOxEaUijph7I7RzWSo48j0Dn+ukdWY6I6IeSHa4NxMPLV+HjYLKU Zrrw== X-Gm-Message-State: APjAAAUA+/AlGtnksXihG3bXXAaiJHD4Am5lx+WX0wB/2HsNlETyI0ti SXp7ZfC/WgQ/c/wRrkhMN9E= X-Google-Smtp-Source: APXvYqyA5fcvHE6s/QW8hqU045tyKunvg7YpfxWYKIvmWVP3hGtod6BsKPA95cAxnnkBvONfuZnUdw== X-Received: by 2002:adf:f60e:: with SMTP id t14mr34733290wrp.39.1555076306486; Fri, 12 Apr 2019 06:38:26 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.25 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:26 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 15/30] tools/lib/traceevent: Man pages for event find APIs Date: Fri, 12 Apr 2019 16:37:56 +0300 Message-Id: <20190412133811.15878-16-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_find_event() tep_find_event_by_name() tep_find_event_by_record() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_find.txt | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt new file mode 100644 index 000000000000..797a5cb4e38a --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt @@ -0,0 +1,101 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_event,tep_find_event_by_name,tep_find_event_by_record - +Find events by given key. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_); +struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_); +struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_); +-- + +DESCRIPTION +----------- +This set of functions can be used to search for an event, based on a given +criteria. All functions require a pointer to a _tep_, trace event parser +context. + +The _tep_find_event()_ function searches for an event by given event _id_. + +The tep_find_event_by_name()_ function searches for an event by given +event _name_, under the system _sys_. If the _sys_ is NULL (not specified), +the first event with _name_ is returned. + +The tep_find_event_by_record()_ function searches for an event from a given +_record_. + +RETURN VALUE +------------ +All these functions return a pointer to the found event, or NULL if there is no +such event. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event; + +event = tep_find_event(tep, 1857); +if (event == NULL) { + /* There is no event with ID 1857 */ +} + +event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +if (event == NULL) { + /* There is no kvm_exit event, from kvm system */ +} + +void event_from_record(struct tep_record *record) +{ + struct tep_event *event = tep_find_event_by_record(tep, record); + if (event == NULL) { + /* There is no event from given record */ + } +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:57 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898347 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 1400118B7 for ; Fri, 12 Apr 2019 13:38:30 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id EFF5D28EC3 for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id EE2D828E13; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7B1F028ECA for ; Fri, 12 Apr 2019 13:38:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727006AbfDLNi3 (ORCPT ); Fri, 12 Apr 2019 09:38:29 -0400 Received: from mail-wr1-f68.google.com ([209.85.221.68]:41398 "EHLO mail-wr1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726911AbfDLNi3 (ORCPT ); Fri, 12 Apr 2019 09:38:29 -0400 Received: by mail-wr1-f68.google.com with SMTP id r4so11965617wrq.8 for ; Fri, 12 Apr 2019 06:38:27 -0700 (PDT) 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=oaPIgFhnw3nZP94vy4cUagZ1XhQY6w1o32hV3EJD3ig=; b=sW52J0oBQ0LZvqj/B58w783Qcq/WTiMcGTENBfiDtQVN7OZXnGldy6BnjDwrkVnIq5 YEB4Cj0ZD8GexqxxfMx8U2ueYf1xgxyyFV7z0Op+0ZH7XV8iJbCGRiPc0oXPV14we2iK Rl+l3tHjPqJ25d0+/oDHUSoa30u/dsztBcrkZPpDkba8eW5x6FgD5sHyM+MlmVEMEfBH 7Hm/OLhJRvKQXAHIqb2f+uqr6yYLgtLApp3S7o4k4acu1lMLKjCzuEhfl2kpD9U255os mw5SywJ7yrXLH2GTEdZ4y03zm5fHG02JPNIwXMBM+rjCmyB5FdgBNIkS/0LbY14X0KwT Nepw== X-Gm-Message-State: APjAAAXk+fmOOrOMP6iw9ImhmoFBM0ws29sTCkvuKxhxAoJLIYuS9qln jM4tSPz7SqkWQqksGaWMBZUNFqwX X-Google-Smtp-Source: APXvYqxfUdC0l9DK95Sn650MLfJSi3U8D7mWdQhHqlradM7lCzUG1BdTm4HITFLJ70tDnWH42qEShg== X-Received: by 2002:adf:e288:: with SMTP id v8mr29978662wri.7.1555076307371; Fri, 12 Apr 2019 06:38:27 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.26 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:26 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 16/30] tools/lib/traceevent: Man page for list events APIs Date: Fri, 12 Apr 2019 16:37:57 +0300 Message-Id: <20190412133811.15878-17-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for libtraceevent APIs: tep_list_events() tep_list_events_copy() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_list.txt | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt new file mode 100644 index 000000000000..3776e84bba8b --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt @@ -0,0 +1,121 @@ +libtraceevent(3) +================ + +NAME +---- +tep_list_events, tep_list_events_copy - +Get list of events, sorted by given criteria. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_event_sort_type* { + _TEP_EVENT_SORT_ID_, + _TEP_EVENT_SORT_NAME_, + _TEP_EVENT_SORT_SYSTEM_, +}; + +struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_); +struct tep_event pass:[*]pass:[*]*tep_list_events_copy*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_); +-- + +DESCRIPTION +----------- +The _tep_list_events()_ function returns an array of pointers to the events, +sorted by the _sort_type_ criteria. The last element of the array is NULL. +The returned memory must not be freed, it is managed by the library. +The function is not thread safe. The _tep_ argument is trace event parser +context. The _sort_type_ argument is the required sort criteria: +[verse] +-- + _TEP_EVENT_SORT_ID_ - sort by the event ID. + _TEP_EVENT_SORT_NAME_ - sort by the event (name, system, id) triplet. + _TEP_EVENT_SORT_SYSTEM_ - sort by the event (system, name, id) triplet. +-- + +The _tep_list_events_copy()_ is a thread safe version of _tep_list_events()_. +It has the same behavior, but the returned array is allocated internally and +must be freed by the caller. + +RETURN VALUE +------------ +The _tep_list_events()_ function returns an array of pointers to events. +In case of an error, NULL is returned. The returned array must not be freed, +it is managed by the library. + +The _tep_list_events_copy()_ function returns an array of pointers to events. +In case of an error, NULL is returned. The returned array must be freed by +the caller. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i; +struct tep_event_format **events; + +i=0; +events = tep_list_events(tep, TEP_EVENT_SORT_ID); +if (events == NULL) { + /* Failed to get the events, sorted by ID */ +} else { + while(events[i]) { + /* walk through the list of the events, sorted by ID */ + i++; + } +} + +i=0; +events = tep_list_events_copy(tep, TEP_EVENT_SORT_NAME); +if (events == NULL) { + /* Failed to get the events, sorted by name */ +} else { + while(events[i]) { + /* walk through the list of the events, sorted by name */ + i++; + } + free(events); +} + +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:58 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898351 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D840A14DB for ; Fri, 12 Apr 2019 13:38:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B572B28ED8 for ; Fri, 12 Apr 2019 13:38:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id B3A4F28EDA; Fri, 12 Apr 2019 13:38:31 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1E40728EDC for ; Fri, 12 Apr 2019 13:38:31 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726911AbfDLNia (ORCPT ); Fri, 12 Apr 2019 09:38:30 -0400 Received: from mail-wm1-f68.google.com ([209.85.128.68]:50248 "EHLO mail-wm1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726998AbfDLNia (ORCPT ); Fri, 12 Apr 2019 09:38:30 -0400 Received: by mail-wm1-f68.google.com with SMTP id z11so11357154wmi.0 for ; Fri, 12 Apr 2019 06:38:28 -0700 (PDT) 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=AFwVAijLoCh30tb6KrgZ0JsJmiHOCnKRknkIp8Jy59E=; b=RholWza6FE7BDli2GI+/psFEsIrRjEfCZ5K9A+CwYtfaSIvqFHP7igb5V955KjNCjw MwF3ZSsFUkTjVvUSQHNcLQJq5t7vkyn4XLsJhCAFHso4ptJ6/mOSWJdmKcRICCoDERo6 oI4JrP2uUADU+h+LhtH3ApOw3WFiA7jEYVm4DfV9mtb/xJBMwwo1o5fVahu9ON9/hCqU 869NIdENU8vn44Xqj5jgXDMZBqprAd3nBfu02HKu1tBcJU9rfYi+vTbE6QlAqKHT4Nek pYlm802jf0ujK4BdGZrMBNYGykpnIPHucdw062q05N0Wtzj91htIpP8vjsbR6/VsAp0p Qcew== X-Gm-Message-State: APjAAAX54R5wBi/qDzeSpBJRdzwnbtV/Xd79gSb+8L1JC/1P7X+gspR8 23KMyQuVBdBGRR+OCAhd8aImT87X X-Google-Smtp-Source: APXvYqxUEQ4gN5EyATtSTyYjPDE9Uf5oeMJgd/4AXRkUvAHSxjes/qwECnDuBJ6/R9O9H8LTeyl3jA== X-Received: by 2002:a7b:c3d7:: with SMTP id t23mr10739487wmj.62.1555076308315; Fri, 12 Apr 2019 06:38:28 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.27 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:27 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 17/30] tools/lib/traceevent: Man pages for libtraceevent event print related APIs Date: Fri, 12 Apr 2019 16:37:58 +0300 Message-Id: <20190412133811.15878-18-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Added new man pages, describing libtraceevent event print related APIs: tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task(), tep_print_event_time(), tep_set_print_raw() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_print.txt | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt new file mode 100644 index 000000000000..2a0dec71fd99 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt @@ -0,0 +1,138 @@ +libtraceevent(3) +================ + +NAME +---- +tep_print_event, tep_print_event_data, tep_event_info, tep_print_event_task, +tep_print_event_time, tep_set_print_raw - Parses the data into the print format. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *tep_print_event_time*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]record, bool _use_trace_clock_); +void *tep_print_event_task*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_print_event_data*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, bool _use_trace_clock_); +void *tep_set_print_raw*(struct tep_handle pass:[*]_tep_, int _print_raw_); +-- + +DESCRIPTION +----------- +The _tep_print_event_time()_ function writes the timestamp of the given _record_ +into the trace sequence _s_. The _tep_ argument is trace event parser context. +The _use_trace_clock_ argument indicates if the tep->trace_clock should be used +for parsing the timestamp. + +The _tep_print_event_task()_ function writes the task command, pid and CPU of +the given _record_ using the given _event_ information into the trace sequence +_s_. The _tep_ argument is trace event parser context. + +The _tep_event_info()_ function parses the raw data from the _record_ using +the given _event_ information and writes the print format into the trace +sequence _s_. + +The _tep_print_event_data()_ function writes the name of the _record_ using the +given _event_ information into the trace sequence _s_ and calls +_tep_event_info()_ to parse and write the raw data from the _record_. The _tep_ +argument is trace event parser context. + +The _tep_print_event()_ function writes the _record_ information. It finds the +corresponding event and calls _tep_print_event_task()_, _tep_print_event_time()_ +and _tep_print_event_data()_ to parse and write the information, into the trace +sequence _s_. The _tep_ argument is trace event parser context. +The _use_trace_clock_ argument indicates if the tep->trace_clock should be used +for parsing the timestamp. + +The _tep_set_print_raw()_ function forces event's information to be printed in +raw format. It changes the behavior of _tep_event_info()_ function. The _tep_ +argument is trace event parser context. The _print_raw_ argument specifies +whether to print in raw format or not. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +struct tep_handle *tep = tep_alloc(); +... +void print_my_event(struct tep_record *record) +{ + struct tep_event *event; + + /* print all event information */ + trace_seq_reset(&seq); + tep_print_event(tep, &seq, record, TRUE); + + event = tep_find_event_by_record(tep, record); + + if (event != NULL) { + /* print event timestamp */ + trace_seq_reset(&seq); + tep_print_event_time(tep, &seq, event, record, TRUE); + + /* print event task information */ + trace_seq_reset(&seq); + tep_print_event_task(tep, &seq, event, record); + + /* print event name and raw data */ + trace_seq_reset(&seq); + tep_print_event_data(tep, &seq, event, record); + + /* print event raw data */ + trace_seq_reset(&seq); + tep_event_info(&seq, event, record); + + /* print event raw data in raw format */ + trace_seq_reset(&seq); + tep_set_print_raw(tep, 1); + tep_event_info(&seq, event, record); + } +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences related APIs. + Trace sequences are used to allow a function to call several other functions + to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:37:59 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898349 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 42BC617E0 for ; Fri, 12 Apr 2019 13:38:32 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1CA7F28DFB for ; Fri, 12 Apr 2019 13:38:32 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1AD4928EF7; Fri, 12 Apr 2019 13:38:32 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7822928DFB for ; Fri, 12 Apr 2019 13:38:31 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726946AbfDLNib (ORCPT ); Fri, 12 Apr 2019 09:38:31 -0400 Received: from mail-wr1-f65.google.com ([209.85.221.65]:36913 "EHLO mail-wr1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727021AbfDLNib (ORCPT ); Fri, 12 Apr 2019 09:38:31 -0400 Received: by mail-wr1-f65.google.com with SMTP id w10so12024263wrm.4 for ; Fri, 12 Apr 2019 06:38:29 -0700 (PDT) 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=B+Ei2QhpQrkv3h8J1/NRM3Vibn/+b9Kac0vIj2+fXp8=; b=h7URLwg5a/+YHgXAaoZZzlevKcFQRh5iUhObGZ55YZn1rW3awRdjSo4Aq6RKwlLLQW Tr90u1YnJ+/l5m//WFJZZoy3gvmobRlziJkvCOy44/Y44E5r4mEBTNCDWfxUinZNVBck MOXOXL/F3bKOQ8+n878nXMAxH0ci5LKmaudEgtwlfowOmPkn2TbQPUWXBve2leBETAPd sQghp1JttLlPeTXgylDPpA0m4bcY4ZjYeY9WUuvpBFjmOQQG80Cw3Sg/W/8XQ+9RvjSV RIlFdSQVYM/9QypQWCN3P/+Tm3o7iv2yMwdCFvrKIA5emoITYL3fjt3OxggQN6+bl5Uv MNdg== X-Gm-Message-State: APjAAAWZmdagvRr2FEU36RukBPkVtWL8/CIdmanyTZR9uKaConL6lH3z hFDJSc1Bk/jkV/4bNcwhpJlV61oy X-Google-Smtp-Source: APXvYqyxrYkIUN352OUKeXbvdX/7eM+R38cjAhKTq3PrJiirTrDbKglzFst81feuFosTwrvwfhLvtA== X-Received: by 2002:a5d:6b04:: with SMTP id v4mr32867349wrw.69.1555076309155; Fri, 12 Apr 2019 06:38:29 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.28 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:28 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 18/30] tools/lib/traceevent: Man pages for libtraceevent event get APIs Date: Fri, 12 Apr 2019 16:37:59 +0300 Message-Id: <20190412133811.15878-19-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_get_event(), tep_get_first_event(), tep_get_events_count() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-event_get.txt | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_get.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_get.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_get.txt new file mode 100644 index 000000000000..6525092fc417 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_get.txt @@ -0,0 +1,99 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_event, tep_get_first_event, tep_get_events_count - Access events. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event pass:[*]*tep_get_event*(struct tep_handle pass:[*]_tep_, int _index_); +struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_); +int *tep_get_events_count*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +The _tep_get_event()_ function returns a pointer to event at the given _index_. +The _tep_ argument is trace event parser context, the _index_ is the index of +the requested event. + +The _tep_get_first_event()_ function returns a pointer to the first event. +As events are stored in an array, this function returns the pointer to the +beginning of the array. The _tep_ argument is trace event parser context. + +The _tep_get_events_count()_ function returns the number of the events +in the array. The _tep_ argument is trace event parser context. + +RETURN VALUE +------------ +The _tep_get_event()_ returns a pointer to the event located at _index_. +NULL is returned in case of error, in case there are no events or _index_ is +out of range. + +The _tep_get_first_event()_ returns a pointer to the first event. NULL is +returned in case of error, or in case there are no events. + +The _tep_get_events_count()_ returns the number of the events. 0 is +returned in case of error, or in case there are no events. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i,count = tep_get_events_count(tep); +struct tep_event *event, *events = tep_get_first_event(tep); + +if (events == NULL) { + /* There are no events */ +} else { + for (i = 0; i < count; i++) { + event = (events+i); + /* process events[i] */ + } + + /* Get the last event */ + event = tep_get_event(tep, count-1); +} +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:00 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898353 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 8B61E1515 for ; Fri, 12 Apr 2019 13:38:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6F22B28EEA for ; Fri, 12 Apr 2019 13:38:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 63EA428EF6; Fri, 12 Apr 2019 13:38:33 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 937E128EEA for ; Fri, 12 Apr 2019 13:38:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726998AbfDLNic (ORCPT ); Fri, 12 Apr 2019 09:38:32 -0400 Received: from mail-wm1-f65.google.com ([209.85.128.65]:37924 "EHLO mail-wm1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNic (ORCPT ); Fri, 12 Apr 2019 09:38:32 -0400 Received: by mail-wm1-f65.google.com with SMTP id w15so11076221wmc.3 for ; Fri, 12 Apr 2019 06:38:30 -0700 (PDT) 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=c7OpjGTjS/0SCcfU9EFvP5Z6UhyFladJ5cnJxnD1qJs=; b=oPwmMctF+E2IlbNDFImr9J07zFoKz8yXRW0JaHJAJsrK13hTlvA87bHthHCz92Nd9Y 4s3IqCGTBR5axHiTrVxaei9XJG84fBGxpLXKmEPt9+R/ZV62wdJBqA+FFt+aeuTHEPZC NAcJMOBwpmj4D9OohyWkhS0W9DcZbPt7Ns0Ddcenoy+oUnvROo3ktWowy6/ykwAo2ceC vASrc8SrbeTM8fgRrGtTwpKHm5oGcocRfhhrU1MTf6QEaruYG43KNgu2yreo2ckwDVX7 1o5GnwQp/C1T454tVj5OJ4+wrFPmChBlQrAIF7uPcdieIN1f3FqR3f7/sMrqG9wiEwyS TnBg== X-Gm-Message-State: APjAAAVH5rItIo+Ip8pUMkyujtbXnk1Tx8GbJcTPGN/evlQgds1dtjVB R+jPoMMWYgcuWxDg+XecIfFBGvaf X-Google-Smtp-Source: APXvYqxEnJ+PAkqjiR6pjsqjSoHIqTDJ3JX1aUw2jNjWClfecRHZf3kU6rCOwbapcuENVvVzxdzD0g== X-Received: by 2002:a1c:a9cb:: with SMTP id s194mr11578754wme.62.1555076310064; Fri, 12 Apr 2019 06:38:30 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.29 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:29 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 19/30] tools/lib/traceevent: Man pages find field APIs Date: Fri, 12 Apr 2019 16:38:00 +0300 Message-Id: <20190412133811.15878-20-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_find_common_field(), tep_find_field() tep_find_any_field() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_find.txt | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt new file mode 100644 index 000000000000..0896af5b9eff --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt @@ -0,0 +1,118 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_common_field, tep_find_field, tep_find_any_field - +Search for a field in an event. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); +struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_); +struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); +-- + +DESCRIPTION +----------- +These functions search for a field with given name in an event. The field +returned can be used to find the field content from within a data record. + +The _tep_find_common_field()_ function searches for a common field with _name_ +in the _event_. + +The _tep_find_field()_ function searches for an event specific field with +_name_ in the _event_. + +The _tep_find_any_field()_ function searches for any field with _name_ in the +_event_. + +RETURN VALUE +------------ +The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_ +functions return a pointer to the found field, or NULL in case there is no field +with the requested name. + +EXAMPLE +------- +[source,c] +-- +#include +... +void get_htimer_info(struct tep_handle *tep, struct tep_record *record) +{ + struct tep_format_field *field; + struct tep_event *event; + long long softexpires; + int mode; + int pid; + + event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); + + field = tep_find_common_field(event, "common_pid"); + if (field == NULL) { + /* Cannot find "common_pid" field in the event */ + } else { + /* Get pid from the data record */ + pid = tep_read_number(tep, record->data + field->offset, + field->size); + } + + field = tep_find_field(event, "softexpires"); + if (field == NULL) { + /* Cannot find "softexpires" event specific field in the event */ + } else { + /* Get softexpires parameter from the data record */ + softexpires = tep_read_number(tep, record->data + field->offset, + field->size); + } + + field = tep_find_any_field(event, "mode"); + if (field == NULL) { + /* Cannot find "mode" field in the event */ + } else + { + /* Get mode parameter from the data record */ + mode = tep_read_number(tep, record->data + field->offset, + field->size); + } +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:01 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898355 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9FC7F14DB for ; Fri, 12 Apr 2019 13:38:34 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 82D0628EC5 for ; Fri, 12 Apr 2019 13:38:34 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8182E28ECC; Fri, 12 Apr 2019 13:38:34 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id BE18328EFC for ; Fri, 12 Apr 2019 13:38:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727022AbfDLNid (ORCPT ); Fri, 12 Apr 2019 09:38:33 -0400 Received: from mail-wm1-f67.google.com ([209.85.128.67]:35882 "EHLO mail-wm1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726954AbfDLNid (ORCPT ); Fri, 12 Apr 2019 09:38:33 -0400 Received: by mail-wm1-f67.google.com with SMTP id h18so11090349wml.1 for ; Fri, 12 Apr 2019 06:38:31 -0700 (PDT) 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=1bQE3TTFSmDOY6FHgV61Pevw3gusRyfrEHXS0IauMjA=; b=OMdStb0Sa28PFCH140UqzYt24xj7aDd7jbk5C19+hOHvMGJOoJDyHzZbWh/TO/oocZ VnND/vljVqQXes0jY/Svq6f5yNGViH1+y4NBxdtmC6VnZBitw8YDYkO6M/mYgQmig76a rT4B7OOmALO6fJPFt07B4pJEnOVSzoMxzFTHnxV5yGqtuMjjicTP46P7JAbFN+Y8mWH3 9DTpO6cDRVOrkBHlfQzdkclkgfDH+R4ofTePJFfX62u4TdnIwYXUQ8MtDxoTRtcpWfJU /xdfpMjYkb1/prCAXrvvnV7evvzZVgvhpIpl0DSJm93LHYfxksSjNmodCUP/Ln/5VXmz OD3Q== X-Gm-Message-State: APjAAAWZLo9xWydUa5cF6CNib9ZcnoOx3XRVL82S6vdDcIjXy9t+uS/H D62x8hoXR2I2wj5eJDN+PeYao7bW X-Google-Smtp-Source: APXvYqzI53gzhvRlusxLjTNd2U8DJsH6RkgOftLQ4SyQAeb/aXbhKuWcLrqUMZqGaqWPXHQaKORbMw== X-Received: by 2002:a1c:4187:: with SMTP id o129mr11007739wma.57.1555076311154; Fri, 12 Apr 2019 06:38:31 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.30 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:30 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 20/30] tools/lib/traceevent: Man pages get field value APIs Date: Fri, 12 Apr 2019 16:38:01 +0300 Message-Id: <20190412133811.15878-21-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val(), tep_get_field_raw() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_get_val.txt | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt new file mode 100644 index 000000000000..b71b407b23e9 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt @@ -0,0 +1,121 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_any_field_val, tep_get_common_field_val, tep_get_field_val, +tep_get_field_raw - Get value of a field. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_); +-- + +DESCRIPTION +----------- +These functions can be used to find a field and retrieve its value. + +The _tep_get_any_field_val()_ function searches in the _record_ for a field +with _name_, part of the _event_. If the field is found, its value is stored in +_val_. If there is an error and _err_ is not zero, then an error string is +written into _s_. + +The _tep_get_common_field_val()_ function does the same as +_tep_get_any_field_val()_, but searches only in the common fields. This works +for any event as all events include the common fields. + +The _tep_get_field_val()_ function does the same as _tep_get_any_field_val()_, +but searches only in the event specific fields. + +The _tep_get_field_raw()_ function searches in the _record_ for a field with +_name_, part of the _event_. If the field is found, a pointer to its raw data +is returned. The size of the data is stored in _len_. If there is an error and +_err_ is not zero, then an error string is written into _s_. + +RETURN VALUE +------------ +The _tep_get_any_field_val()_, _tep_get_common_field_val()_ and +_tep_get_field_val()_ functions return 0 on success, or -1 in case of an error. + +The _tep_get_field_raw()_ function returns a pointer to field's raw data, and +places the length of this data in _len_. In case of an error NULL is returned. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +... +void process_record(struct tep_record *record) +{ + int len; + char *comm; + struct tep_event_format *event; + unsigned long long val; + + event = tep_find_event_by_record(pevent, record); + if (event != NULL) { + if (tep_get_common_field_val(NULL, event, "common_type", + record, &val, 0) == 0) { + /* Got the value of common type field */ + } + if (tep_get_field_val(NULL, event, "pid", record, &val, 0) == 0) { + /* Got the value of pid specific field */ + } + comm = tep_get_field_raw(NULL, event, "comm", record, &len, 0); + if (comm != NULL) { + /* Got a pointer to the comm event specific field */ + } + } +} +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences + related APIs. Trace sequences are used to allow a function to call + several other functions to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:02 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898357 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 6F9881515 for ; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 53F3C28EC7 for ; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 51E7228EC8; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AC56E28EC5 for ; Fri, 12 Apr 2019 13:38:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726954AbfDLNie (ORCPT ); Fri, 12 Apr 2019 09:38:34 -0400 Received: from mail-wm1-f66.google.com ([209.85.128.66]:51534 "EHLO mail-wm1-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNie (ORCPT ); Fri, 12 Apr 2019 09:38:34 -0400 Received: by mail-wm1-f66.google.com with SMTP id 4so11293959wmf.1 for ; Fri, 12 Apr 2019 06:38:32 -0700 (PDT) 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=QyKgGJb830tj2VKYVpZN0GpSFpkJhoqYtjtCcSNAbW4=; b=QoayqtEMWbEEMTkM/2LJBw5vpHjdyz1gF7CTP3X5EvToWjZPIlEQvg564ikR3GY+oD 5Y/kbyHNRPnLEbSurdzKcg+iVoaRtwJ9uc2+8byzV5fjoT6+T6M3rhLQAozGyoytNZQC 9VXclUt4umrNzqZrsXxT1TTCh4aI3ZbFkZpWUsp4KhJnJ4kiZCXzInz/eLoGZi05qCf+ /SXpobqJ5p86Z/YlYXwgurptkRhCb95YCiX0GrFbJX6bfNTjsuBo9qw1+SGTvL30/yHy XrCRxdJH8aLgXbNss81//jk9QNYWAsAntYnhxiPhGchpkUGISJRfw2cHAA0aEbkaKD3M dBQw== X-Gm-Message-State: APjAAAUKZE4HWXirSWJj026gHZ0dUnmAU92TTS6U5RlgydQQ1aXWWn2N JQTUvLBKviNjZzwe5SaD4L/36oxU X-Google-Smtp-Source: APXvYqzGqHEx3sxHUsOkVVb5Y/3UPfUP1YSaDxyVA2M7++7dxs/Wlq/OZtWPnXgRep4X6Q0ih7Iu0Q== X-Received: by 2002:a1c:730c:: with SMTP id d12mr11531302wmb.10.1555076312034; Fri, 12 Apr 2019 06:38:32 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.31 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:31 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 21/30] tools/lib/traceevent: Man pages for print field APIs Date: Fri, 12 Apr 2019 16:38:02 +0300 Message-Id: <20190412133811.15878-22-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_print_field(), tep_print_fields(), tep_print_num_field(), tep_print_func_field() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_print.txt | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt new file mode 100644 index 000000000000..7305e2391805 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt @@ -0,0 +1,121 @@ +libtraceevent(3) +================ + +NAME +---- +tep_print_field, tep_print_fields, tep_print_num_field, tep_print_func_field - +Print the field content. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_); +void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_); +int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); +int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); +-- + +DESCRIPTION +----------- +These functions print recorded field's data, according to the field's type. + +The _tep_print_field()_ function extracts from the recorded raw _data_ value of +the _field_ and prints it into _s_, according to the field type. + +The _tep_print_fields()_ prints recorded values of all _event_'s fields. It +iterates all fileds of the _event_, and calls _tep_print_field()_ for each of +them. + +The _tep_print_num_field()_ function prints a numeric field with given format +string. A search is performed in the _event_ for a field with _name_. If such +field is found, its value is extracted from the _record_ and is printed in the +_s_, according to the given format string _fmt_. If the argument _err_ is +non-zero, and an error occures - it is printed in the _s_. + +The _tep_print_func_field()_ function prints a function field with given format +string. A search is performed in the _event_ for a field with _name_. If such +field is found, its value is extracted from the _record_. The value is assumed +to be a function address, and a search is perform to find the name of this +function. The function name (if found) and its address are printed in the _s_, +according to the given format string _fmt_. If the argument _err_ is non-zero, +and an error occures - it is printed in _s_. + +RETURN VALUE +------------ +The _tep_print_num_field()_ and _tep_print_func_field()_ functions return 1 +on success, -1 in case of an error or 0 if the print buffer _s_ is full. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct trace_seq seq; +trace_seq_init(&seq); +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); +... +void process_record(struct tep_record *record) +{ + struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid"); + + trace_seq_reset(&seq); + + /* Print the value of "common_pid" */ + tep_print_field(&seq, record->data, field_pid); + + /* Print all fields of the "hrtimer_start" event */ + tep_print_fields(&seq, record->data, record->size, event); + + /* Print the value of "expires" field with custom format string */ + tep_print_num_field(&seq, " timer expires in %llu ", event, "expires", record, 0); + + /* Print the address and the name of "function" field with custom format string */ + tep_print_func_field(&seq, " timer function is %s ", event, "function", record, 0); + } + ... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences related APIs. + Trace sequences are used to allow a function to call several other functions + to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:03 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898359 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9DB6817E0 for ; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8411C28EC2 for ; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8226528ECC; Fri, 12 Apr 2019 13:38:35 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E8A6D28ED6 for ; Fri, 12 Apr 2019 13:38:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727023AbfDLNie (ORCPT ); Fri, 12 Apr 2019 09:38:34 -0400 Received: from mail-wr1-f68.google.com ([209.85.221.68]:39495 "EHLO mail-wr1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727021AbfDLNie (ORCPT ); Fri, 12 Apr 2019 09:38:34 -0400 Received: by mail-wr1-f68.google.com with SMTP id j9so12012510wrn.6 for ; Fri, 12 Apr 2019 06:38:33 -0700 (PDT) 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=XCwqz38+6Na1cuazbbZfVOCxZtol9JZD0vkz8i0Dekc=; b=HRhL5ekUCWERFG7zjO0y6FPeOuBeBSZg/qCqSOav9xFHgfNC5/nfQHlf6JX2ZWuC/g je06oRMzdU2w9wDZc+ivsXF3ToDaYdUi0t67DGk1bl4kdgZtNrk/R0QdR3b8Ikxy39fi iuJIbbiPQSPpzEIAFBZjiY7jr3urXMdSebXyyVI2JVzDX3/tPh9LzXXPugiUixM5qW4q 9t8VaDIBUfbd5odlepaAPKPR//hIPcLsVwyl/0JjqXv34xjHoApoc1zaA7ueevX6En9a 3V9Kx/5IGWqVxmWEHXXILHlsdzVo99nP7X9/0V7PRdyX8A/1YwHHfYjHZIZfsDGwAWm9 SYEg== X-Gm-Message-State: APjAAAW/WWDQPOG6wZNvdggBk/IybtVrGr0KNQylvmVLRPii7lwUdfG9 zd1L5i/HhYtT1ptWnEfxzZY= X-Google-Smtp-Source: APXvYqw+r++6y65F5JUXaJQ7/36wEiXckInMyPvLL/IPPmPSkR+uaHn9LoomveBIjaI7yHsSatutrQ== X-Received: by 2002:a5d:458f:: with SMTP id p15mr35304045wrq.188.1555076313025; Fri, 12 Apr 2019 06:38:33 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.32 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:32 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 22/30] tools/lib/traceevent: Man page for tep_read_number_field() Date: Fri, 12 Apr 2019 16:38:03 +0300 Message-Id: <20190412133811.15878-23-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for libtraceevent API tep_read_number_field(). Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_read.txt | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt new file mode 100644 index 000000000000..0c560c416ac2 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt @@ -0,0 +1,80 @@ +libtraceevent(3) +================ + +NAME +---- +tep_read_number_field - Reads a number from a raw data. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_); +-- + +DESCRIPTION +----------- +The _tep_read_number_field()_ function reads the value of the _field_ from the +raw _data_ and stores it in the _value_. The function sets the _value_ according +to the endianness of the raw data and the current machine. + +RETURN VALUE +------------ +The _tep_read_number_field()_ function retunrs 0 in case of success, or -1 in +case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); +... +void process_record(struct tep_record *record) +{ + unsigned long long pid; + struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid"); + + if (tep_read_number_field(field_pid, record->data, &pid) != 0) { + /* Failed to get "common_pid" value */ + } +} +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:04 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898363 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 02C201515 for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D6E2828DFB for ; Fri, 12 Apr 2019 13:38:37 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D536F28F03; Fri, 12 Apr 2019 13:38:37 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7696028DFB for ; Fri, 12 Apr 2019 13:38:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727027AbfDLNig (ORCPT ); Fri, 12 Apr 2019 09:38:36 -0400 Received: from mail-wm1-f68.google.com ([209.85.128.68]:54793 "EHLO mail-wm1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNif (ORCPT ); Fri, 12 Apr 2019 09:38:35 -0400 Received: by mail-wm1-f68.google.com with SMTP id c1so11282090wml.4 for ; Fri, 12 Apr 2019 06:38:34 -0700 (PDT) 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=lOsh7yjFkyid7emQ5kYbF8wd4NSvXwJPDsEaULG/B+Q=; b=gBW6BOckNiBHbXdKBeRgWdTx8rBtIxBM8A94lutwpOfcpSoTc4ZjwGykCatm1baUD+ QGJtTtsfH1Ixj6SxOTfsPtl7MaRGxEiUOpnSyp8KDUv456F+vjPFVWsXwLCP7a6wFK1+ tX5rPel4u620Jy9Djlruiz4Q60c0qtZ0D05gR7lUG+eT29ILAG7jv/S84IfHYv2JHLpS 6KyOTT3ib91Ge4Q4rZ4msRn5z1GIAFSQCa+K5m5dV6c3oAZHg9bSV1gMfEmeAVi8SN7U diyACSWDTbL58nw1pAe/E2PE1Wla5phjwdsLkqzmrGqbA5LhGmi6jAA/pZE6zQ8w9aoy W/Kw== X-Gm-Message-State: APjAAAVSclbKoiMM70xO2bE6dtQnkYs4dON5GkuPtjrrCJVc4ElWr8aD U8Um4YmM2OVdIURZek2CDcV4H14L X-Google-Smtp-Source: APXvYqzKzCCOa/FdD0UaUSxmL51TLQLH+NXbHhK+nKBJTht3DVM4vMYga00GbjgJY3UG+zZICV+69w== X-Received: by 2002:a7b:c743:: with SMTP id w3mr10964194wmk.75.1555076314065; Fri, 12 Apr 2019 06:38:34 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.33 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:33 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 23/30] tools/lib/traceevent: Man pages for event fields APIs Date: Fri, 12 Apr 2019 16:38:04 +0300 Message-Id: <20190412133811.15878-24-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_event_common_fields(), tep_event_fields() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-fields.txt | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-fields.txt b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt new file mode 100644 index 000000000000..1ccb531d5114 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt @@ -0,0 +1,105 @@ +libtraceevent(3) +================ + +NAME +---- +tep_event_common_fields, tep_event_fields - Get a list of fields for an event. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_); +struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_); +-- + +DESCRIPTION +----------- +The _tep_event_common_fields()_ function returns an array of pointers to common +fields for the _event_. The array is allocated in the function and must be freed +by free(). The last element of the array is NULL. + +The _tep_event_fields()_ function returns an array of pointers to event specific +fields for the _event_. The array is allocated in the function and must be freed +by free(). The last element of the array is NULL. + +RETURN VALUE +------------ +Both _tep_event_common_fields()_ and _tep_event_fields()_ functions return +an array of pointers to tep_format_field structures in case of success, or +NULL in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i; +struct tep_format_field **fields; +struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +if (event != NULL) { + fields = tep_event_common_fields(event); + if (fields != NULL) { + i = 0; + while (fields[i]) { + /* + walk through the list of the common fields + of the kvm_exit event + */ + i++; + } + free(fields); + } + fields = tep_event_fields(event); + if (fields != NULL) { + i = 0; + while (fields[i]) { + /* + walk through the list of the event specific + fields of the kvm_exit event + */ + i++; + } + free(fields); + } +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:05 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898365 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 1FFBE17E0 for ; Fri, 12 Apr 2019 13:38:39 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 021A628ED2 for ; Fri, 12 Apr 2019 13:38:39 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0063C28EEF; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 218E428EEF for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727035AbfDLNii (ORCPT ); Fri, 12 Apr 2019 09:38:38 -0400 Received: from mail-wm1-f67.google.com ([209.85.128.67]:50265 "EHLO mail-wm1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727021AbfDLNih (ORCPT ); Fri, 12 Apr 2019 09:38:37 -0400 Received: by mail-wm1-f67.google.com with SMTP id z11so11357682wmi.0 for ; Fri, 12 Apr 2019 06:38:35 -0700 (PDT) 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=f5yCAbnZCZuiOjMAzwBzpHz2LoDzKckLz/J6WzycyfQ=; b=DCoJK7zMyHjaJoU9sQ0Z72cAelmUm/HME16UthCPTbqAg7aIGLAa/vdMVmDyeOr8xI Kch1uNgsWJi7HTjtcerFwEK2GDYXYDvZUSthfATBUN6a/RElGRgyI1SnbH+o23+GpI/g SBjcbG6bey4sf0VakMKnktKhqD2KTEt5wsvFz7C7sz8AjGTJqFBmuX84WtbwoHSmshaZ oioSQjarUyoRulb6Prw1/F8bS+2ta1VH3kjonbc+3ZNrK3lStW7wpSC7d+ywPz7gObHg PPspijRdUz4Ns1rZK142l2IdI3qlvo7x50ClX56xM32YeUyqR8WXKMX3vw1SAd2xSZSb Ro5Q== X-Gm-Message-State: APjAAAVfhm02FJGAG0KVDYhLo1AANyf0IajHnM9M5fIIG5yajR6+JZ+d wkZQ1Sdx2s9QTx93oUT83A93Eq5i X-Google-Smtp-Source: APXvYqz+PsmiI+e+GBM3eSslp8Mw6BCilVTri9TgynQJqrSVkxyuXuPVc08+qnLW1oTpZyioqT0ZrA== X-Received: by 2002:a1c:cf83:: with SMTP id f125mr11036154wmg.96.1555076314988; Fri, 12 Apr 2019 06:38:34 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.34 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:34 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 24/30] tools/lib/traceevent: Man pages for event filter APIs Date: Fri, 12 Apr 2019 16:38:05 +0300 Message-Id: <20190412133811.15878-25-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Added new man pages, describing libtraceevent event filter APIs: tep_filter_alloc() tep_filter_free() tep_filter_reset() tep_filter_add_filter_str() tep_filter_strerror() tep_event_filtered() tep_filter_remove_event() tep_filter_match() tep_filter_copy() tep_filter_compare() tep_filter_make_string() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-filter.txt | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt new file mode 100644 index 000000000000..df49e4f10697 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt @@ -0,0 +1,210 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_alloc, tep_filter_free, tep_filter_reset, tep_filter_make_string, +tep_filter_copy, tep_filter_compare, tep_filter_match, tep_event_filtered, +tep_filter_remove_event, tep_filter_strerror, tep_filter_add_filter_str - +Event filter related APIs. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_); +void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_); +void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_); +enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_); +int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_); +int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_); +int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_); +char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_); +-- + +DESCRIPTION +----------- +Filters can be attached to traced events. They are useful for picking out only +the desired information, and not to flood the ring buffer with needless events. +Each event can be filtered based on its parameters, described in the event's +format file. This set of functions can be used to create, delete, modify and +attach event filters. + +The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument +is the trace event parser context. + +The _tep_filter_free()_ function frees an event filter and all resources that it +had used. + +The _tep_filter_reset()_ function removes all rules from an event filter and +resets it. + +The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The +_filter_str_ argument is the filter string, that contains the rule. + +The _tep_event_filtered()_ function checks if the event with _event_id_ has +_filter_. + +The _tep_filter_remove_event()_ function removes a _filter_ for an event with +_event_id_. + +The _tep_filter_match()_ function tests if a _record_ matches given _filter_. + +The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter. + +The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_. + +The _tep_filter_make_string()_ function constructs a string, displaying +the _filter_ contents for given _event_id_. + +The _tep_filter_strerror()_ function copies the _filter_ error buffer into the +given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_ +is copied a string, describing the error _err_. + +RETURN VALUE +------------ +The _tep_filter_alloc()_ function returns a pointer to the newly created event +filter, or NULL in case of an error. + +The _tep_filter_add_filter_str()_ function returns 0 if the rule was +successfully added or a negative error code. Use _tep_filter_strerror()_ to see +actual error message in case of an error. + +The _tep_event_filtered()_ function returns 1 if the filter is found for given +event, or 0 otherwise. + +The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or +0 if the event was not found. + +The _tep_filter_match()_ function returns _tep_errno_, according to the result: +[verse] +-- +_pass:[TEP_ERRNO__FILTER_MATCH]_ - filter found for event, the record matches. +_pass:[TEP_ERRNO__FILTER_MISS]_ - filter found for event, the record does not match. +_pass:[TEP_ERRNO__FILTER_NOT_FOUND]_ - no filter found for record's event. +_pass:[TEP_ERRNO__NO_FILTER]_ - no rules in the filter. +-- +or any other _tep_errno_, if an error occurred during the test. + +The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules + were copied. + +The _tep_filter_compare()_ function returns 1 if the two filters hold the same +content, or 0 if they do not. + +The _tep_filter_make_string()_ function returns a string, which must be freed +with free(), or NULL in case of an error. + +The _tep_filter_strerror()_ function returns 0 if message was filled +successfully, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char errstr[200]; +int ret; + +struct tep_event_filter *filter = tep_filter_alloc(tep); +struct tep_event_filter *filter1 = tep_filter_alloc(tep); +ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1"); +if(ret < 0) { + tep_filter_strerror(filter, ret, errstr, sizeof(errstr)); + /* Failed to add a new rule to the filter, the error string is in errstr */ +} +if (tep_filter_copy(filter1, filter) != 0) { + /* Failed to copy filter in filter1 */ +} +... +if (tep_filter_compare(filter, filter1) != 1) { + /* Both filters are different */ +} +... +void process_record(struct tep_handle *tep, struct tep_record *record) +{ + struct tep_event *event; + char *fstring; + + event = tep_find_event_by_record(tep, record); + + if (tep_event_filtered(filter, event->id) == 1) { + /* The event has filter */ + fstring = tep_filter_make_string(filter, event->id); + if (fstring != NULL) { + /* The filter for the event is in fstring */ + free(fstring); + } + } + + switch (tep_filter_match(filter, record)) { + case TEP_ERRNO__FILTER_MATCH: + /* The filter matches the record */ + break; + case TEP_ERRNO__FILTER_MISS: + /* The filter does not match the record */ + break; + case TEP_ERRNO__FILTER_NOT_FOUND: + /* No filter found for record's event */ + break; + case TEP_ERRNO__NO_FILTER: + /* There are no rules in the filter */ + break + default: + /* An error occurred during the test */ + break; + } + + if (tep_filter_remove_event(filter, event->id) == 1) { + /* The event was removed from the filter */ + } +} + +... +tep_filter_reset(filter); +... +tep_filter_free(filter); +tep_filter_free(filter1); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:06 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898367 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id DC3D314DB for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C036C28A85 for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id BE86C28EC6; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4C7C428A85 for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727021AbfDLNii (ORCPT ); Fri, 12 Apr 2019 09:38:38 -0400 Received: from mail-wm1-f66.google.com ([209.85.128.66]:37934 "EHLO mail-wm1-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNih (ORCPT ); Fri, 12 Apr 2019 09:38:37 -0400 Received: by mail-wm1-f66.google.com with SMTP id w15so11076596wmc.3 for ; Fri, 12 Apr 2019 06:38:36 -0700 (PDT) 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=bZ+I1EqMaelYorRhjejZI8WmMDXy0IyI9PEtYxf9P+I=; b=cklJfejBzUWZ2p1NKkcwdHglWTRJWWNGL5/rjwMIwTvj150Vh1qbigzlTlzL2J/qyD PAcaJs8gBp6Ni6c8bo7xvjOgeCyzf+URAK+nPaJa8HIolzEbHsVOMUXgSn/9NxDH+Q6k 2DDc0dRnCGWcw7yXwAQFnawhcAw1mjn1gwdrueN80MghK1bpmOvSvIyjGC6HbRgBCjb3 F3/+YuehMMCQqT4NcEmZdh9RJqckryppe2Q6j4s4pIEXb41znu9AweJH/CwingFBMCaG pGALakd1uan2atDna+2/Y9E7j+BRLbc6cq8wzVhy948GgGKehH6PtrY3xZiYAd3o8IkC tg+g== X-Gm-Message-State: APjAAAVnChxhW087abdrYDBhoiU47WZxK15warf1m2/qBcIwg6oGF1be mmlCERkLWYfwyZdhWvnZ1qQWxjQO X-Google-Smtp-Source: APXvYqwZHNHTwXrLGkNppOax534WrUFcw0GmkDxxpfN7qerPyZpj45sbdySzCsMktgcMkjpIiB41Mg== X-Received: by 2002:a7b:cf2b:: with SMTP id m11mr10313605wmg.56.1555076315998; Fri, 12 Apr 2019 06:38:35 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.35 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:35 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 25/30] tools/lib/traceevent: Man pages for parse event APIs Date: Fri, 12 Apr 2019 16:38:06 +0300 Message-Id: <20190412133811.15878-26-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_parse_event(), tep_parse_format() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-parse_event.txt | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt new file mode 100644 index 000000000000..f248114ca1ff --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt @@ -0,0 +1,90 @@ +libtraceevent(3) +================ + +NAME +---- +tep_parse_event, tep_parse_format - Parse the event format information + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); +enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); +-- + +DESCRIPTION +----------- +The _tep_parse_event()_ function parses the event format and creates an event +structure to quickly parse raw data for a given event. The _tep_ argument is +the trace event parser context. The created event structure is stored in the +_tep_ context. The _buf_ argument is a buffer with _size_, where the event +format data is. The event format data can be taken from +tracefs/events/.../.../format files. The _sys_ argument is the system of +the event. + +The _tep_parse_format()_ function does the same as _tep_parse_event()_. The only +difference is in the extra _eventp_ argument, where the newly created event +structure is returned. + +RETURN VALUE +------------ +Both _tep_parse_event()_ and _tep_parse_format()_ functions return 0 on success, +or TEP_ERRNO__... in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *buf; +int size; +struct tep_event *event = NULL; +buf = read_file("/sys/kernel/tracing/events/ftrace/print/format", &size); +if (tep_parse_event(tep, buf, size, "ftrace") != 0) { + /* Failed to parse the ftrace print format */ +} + +if (tep_parse_format(tep, &event, buf, size, "ftrace") != 0) { + /* Failed to parse the ftrace print format */ +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:07 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898369 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9EFD11874 for ; Fri, 12 Apr 2019 13:38:39 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7316D28EC6 for ; Fri, 12 Apr 2019 13:38:39 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 717D328EC3; Fri, 12 Apr 2019 13:38:39 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id EDFB928E11 for ; Fri, 12 Apr 2019 13:38:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727039AbfDLNii (ORCPT ); Fri, 12 Apr 2019 09:38:38 -0400 Received: from mail-wm1-f65.google.com ([209.85.128.65]:55497 "EHLO mail-wm1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727032AbfDLNii (ORCPT ); Fri, 12 Apr 2019 09:38:38 -0400 Received: by mail-wm1-f65.google.com with SMTP id o25so11275865wmf.5 for ; Fri, 12 Apr 2019 06:38:37 -0700 (PDT) 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=hvSaUKiMrEKZHSsIz9xkKhvhxLIm2GB1TGjnPbucNFo=; b=oUmockxGz/4iy2Pi+meZxSxD7OalHulQol6Jo44FVlD5nPWvRWL/mxLI7XE14uKvGg p/cJ3MRgUWIqc7yHtmd7waHZMBC6T5Nfy/ZOR74arMTNwlpfwvqcGQlLOj/rCkQcxm+L uV8wuljj90AFC8Hf39DfdQnKeMC+2+tUstwHzs1uD725Qqt95vfx9NsKyjhJh+ase6xa myk80f5rSWPUeQRi1pT2bhl3C9Bj5PILh5EbP2dq0SvodjSRtiol9jpjKecRbghHS2B6 Qq2bgN0rn9J20y8pURcDVC9A0jEfWGReQnYq8IXes46fhq5uY24Z7aSAZ/ahSFbXVRCI 83jg== X-Gm-Message-State: APjAAAUWIo9X5eIXye91FIZDA2fg2XL8YNLm8GBA6QobjZUcy+gUJxNy 2b5WYITbz9EXoaPmpFcux7skaYP/ X-Google-Smtp-Source: APXvYqxKfzi4gciNBtMzokOvWk0JFkOMuVI7XVtuSzOtqG/prlXxoUIZXMSFLDb/jhTL8zRn5+x1hA== X-Received: by 2002:a1c:9991:: with SMTP id b139mr10652514wme.53.1555076317028; Fri, 12 Apr 2019 06:38:37 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.36 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:36 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 26/30] tools/lib/traceevent: Man page for tep_parse_header_page() Date: Fri, 12 Apr 2019 16:38:07 +0300 Message-Id: <20190412133811.15878-27-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man page for tep_parse_header_page() libtraceevent API. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-parse_head.txt | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt new file mode 100644 index 000000000000..c90f16c7d8e6 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt @@ -0,0 +1,82 @@ +libtraceevent(3) +================ + +NAME +---- +tep_parse_header_page - Parses the data stored in the header page. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_); +-- + +DESCRIPTION +----------- +The _tep_parse_header_page()_ function parses the header page data from _buf_, +and initializes the _tep_, trace event parser context, with it. The buffer +_buf_ is with _size_, and is supposed to be copied from +tracefs/events/header_page. + +Some old kernels do not have header page info, in this case the +_tep_parse_header_page()_ function can be called with _size_ equal to 0. The +_tep_ context is initialized with default values. The _long_size_ can be used in +this use case, to set the size of a long integer to be used. + +RETURN VALUE +------------ +The _tep_parse_header_page()_ function returns 0 in case of success, or -1 +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *buf; +int size; +buf = read_file("/sys/kernel/tracing/events/header_page", &size); +if (tep_parse_header_page(tep, buf, size, sizeof(unsigned long)) != 0) { + /* Failed to parse the header page */ +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:08 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898371 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D439C14DB for ; Fri, 12 Apr 2019 13:38:40 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B5DA228C9C for ; Fri, 12 Apr 2019 13:38:40 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id B438328ECB; Fri, 12 Apr 2019 13:38:40 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2239428C9C for ; Fri, 12 Apr 2019 13:38:40 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727040AbfDLNik (ORCPT ); Fri, 12 Apr 2019 09:38:40 -0400 Received: from mail-wr1-f65.google.com ([209.85.221.65]:42318 "EHLO mail-wr1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNij (ORCPT ); Fri, 12 Apr 2019 09:38:39 -0400 Received: by mail-wr1-f65.google.com with SMTP id g3so11971750wrx.9 for ; Fri, 12 Apr 2019 06:38:38 -0700 (PDT) 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=ishLnV8MI+ej7L98tC8iAM3HoVJtcTpCifJ1ELtu7UM=; b=ks/G+db42GAAFfAwrTcnxVK/RqQ615KG+D5zGdF2AEIEfwXjanVC1FZPW3QckXAH2R ksziGjOV5SyoLKGhIvsBVoncP6i5vTT7QxIEvYfZW8m7Z02dCS9Rh0DsbbfG9k1CnTHP PebioXcrD3nFguCA1MgPbx4G0pQev138Plb55sHDQCYJHTTNMK5/SxZTAivvv605zmaZ 0Y34F1KIppAL3vHAwjvNsqekcZbc75yKtJxJwwuhQo25SDiFKusUN/MZ2kO5FWR5GJI7 snF/euLaNK1LZKl8P1wg4+ehf9HXuwb8O+NpFHpz83UviE3Yq4dTNY8j8+5vuS+qHIIx iwzQ== X-Gm-Message-State: APjAAAWweeW7miX75319R+/RDP+oOeCK0j049P1MyngIMnQCYUvXf3zd mijMNgcRtQCeZdtkvLvDptM= X-Google-Smtp-Source: APXvYqxqdw9NBRTGB+d8ACzXCQzipvwlg7+0oRsvvQoIw2+RizlBTMv8erxbMy0uH+/vJv/lKY1Zzg== X-Received: by 2002:a5d:6b04:: with SMTP id v4mr32867851wrw.69.1555076317989; Fri, 12 Apr 2019 06:38:37 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.37 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:37 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 27/30] tools/lib/traceevent: Man pages for tep plugins APIs Date: Fri, 12 Apr 2019 16:38:08 +0300 Message-Id: <20190412133811.15878-28-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_load_plugins(), tep_unload_plugin() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-plugins.txt | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt new file mode 100644 index 000000000000..cecc7050c8f4 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt @@ -0,0 +1,98 @@ +libtraceevent(3) +================ + +NAME +---- +tep_load_plugins, tep_unload_plugins - Load / unload traceevent plugins. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_); +void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +The _tep_load_plugins()_ function loads all plugins, located in the plugin +directories. The _tep_ argument is trace event parser context. +The plugin directories are : +[verse] +-- + - System's plugin directory, defined at the library compile time. It + depends on the library installation prefix and usually is + _(install_preffix)/lib/traceevent/plugins_ + - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ + - User's plugin directory, located at _~/.traceevent/plugins_ +-- +Loading of plugins can be controlled by the _tep_flags_, using the +_tep_set_flag()_ API: +[verse] +-- + _TEP_DISABLE_SYS_PLUGINS_ - do not load plugins, located in + the system's plugin directory. + _TEP_DISABLE_PLUGINS_ - do not load any plugins. +-- +The _tep_set_flag()_ API must be called before _tep_load_plugins()_. + +The _tep_unload_plugins()_ function unloads the plugins, previously loaded by +_tep_load_plugins()_. The _tep_ argument is trace event parser context. The +_plugin_list_ is the list of loaded plugins, returned by +the _tep_load_plugins()_ function. + +RETURN VALUE +------------ +The _tep_load_plugins()_ function returns a list of successfully loaded plugins, +or NULL in case no plugins are loaded. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_plugin_list *plugins = tep_load_plugins(tep); +if (plugins == NULL) { + /* no plugins are loaded */ +} +... +tep_unload_plugins(plugins, tep); +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_, _tep_set_flag(3)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:09 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898373 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id DB32214DB for ; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id BDCD828F03 for ; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id BC27A28ED7; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CDDA828B3B for ; Fri, 12 Apr 2019 13:38:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727041AbfDLNil (ORCPT ); Fri, 12 Apr 2019 09:38:41 -0400 Received: from mail-wr1-f68.google.com ([209.85.221.68]:41425 "EHLO mail-wr1-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727032AbfDLNil (ORCPT ); Fri, 12 Apr 2019 09:38:41 -0400 Received: by mail-wr1-f68.google.com with SMTP id r4so11966519wrq.8 for ; Fri, 12 Apr 2019 06:38:39 -0700 (PDT) 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=qXfpYV/7hGD7mBqfVtObRA4PvFqsVhDjky1Vxeg/w50=; b=GujQYEs5nCugzNDQsWSV77JjZgTo+eDmcZ2B+ZyM9ThUPDg9B4DFeerrG5DPanCOrr MBgU4yJKm5vTPsqaM9MFrrMg4ovEKCA3lKuOZhWEi/xy2tLbtKpwyHwz8jEKSaAyegEx 0gBR4U/Ezi15dD1FN21J1Rh8B+cvaUGzG1/0VyqZUHgSyapLkZnCM1TVeOROwis8qPdr RmkC3KoazqwOMF1pAvRe7fO8SQZZkyW03twPYFMcizhmRNUQrC3HhINqc1ASFLFz+Ha/ 01FSUAKYi2Tjh0JVUvgpvCbn4Yy8i18cHsTK/Fc6wj2aeH9mmxuwV3+zTLJSC6j7ujwf 9Xvw== X-Gm-Message-State: APjAAAWrPQdviiaWTt4pD9taNCoP+fE1vUUzM2w/cTbVrarg7Prn91Ci CaPMQMX0gbKFUJXj3aqnP8m0O6al X-Google-Smtp-Source: APXvYqxjboqx9nJdQUUF2ErkZvv8wXnL1wKM0rzdWqT2OBk02TSgjuXEzchYinfCalzLtfSKi/SpmA== X-Received: by 2002:adf:afd7:: with SMTP id y23mr34556922wrd.254.1555076319183; Fri, 12 Apr 2019 06:38:39 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.38 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:38 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 28/30] tools/lib/traceevent: Man pages for "latency format" APIs Date: Fri, 12 Apr 2019 16:38:09 +0300 Message-Id: <20190412133811.15878-29-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_set_latency_format(), tep_is_latency_format(), tep_data_latency_format() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-latency_format.txt | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file mode 100644 index 000000000000..3a3c9e9866ec --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt @@ -0,0 +1,154 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_latency_format, tep_is_latency_format, tep_data_latency_format - +"latency output" format APIs. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_); +bool *tep_is_latency_format*(struct tep_handle pass:[*]_tep_); +void *tep_data_latency_format*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_); + +-- + +DESCRIPTION +----------- +"Latency output" format prints information about interrupts being disabled, +soft irq being disabled, the "need_resched" flag being set and preempt count. +This information is recorded with every event, but by default is not printed. + +The _tep_set_latency_format()_ function enables the "latency output" printing. +The _tep_ argument is trace event parser context. The _lat_ argument can be +zero, for "latency output" disabled, or non zero for "latency output" enabled. +Information is displayed with 6 characters. When a field is zero, or N/A, +a pass:['.'] is printed. Example: +[verse] +-- + -0 0d.h1 106467.859747: function: ktime_get <-- tick_check_idle +-- +The 0d.h1. denotes this information. The first character is never a pass:['.'] +and represents what CPU the trace was recorded on (CPU 0). The pass:['d'] +denotes that interrupts were disabled. The pass:['.'] is "need_resched" flag. +If it is set, the character ['N'] would be displayed. The pass:['h'] means that +this was called inside an interrupt handler. The pass:['1'] is the preemption +disabled (preempt_count) was set to one. See 'LATENCY FORMAT' section. + +The _tep_is_latency_format()_ function gets if "latency output" is enabled. + +The _tep_data_latency_format()_ function parses out the latency format from +_record_ and writes it into _s_. The _tep_ argument is the trace event parser +context. + +This "Latency output" setting affects output of _tep_print_event_task()_ +and _tep_print_event_time()_ APIs. + +LATENCY FORMAT +-------------- +The latency format displays 5 or more fields: +[verse] +-- +CPU #, interrupt state, scheduling state, current context, and preemption count. + +Field 1 is the CPU number (starting with zero). + +Field 2 is the interrupt enabled state: + d : Interrupts are disabled + . : Interrupts are enabled + X : The architecture does not support this information + +Field 3 is the "need resched" state. + N : The task is set to call the scheduler when possible, as another + higher priority task may need to be scheduled in. + . : The task is not set to call the scheduler. + +Field 4 is the context state. + . : Normal context + s : Soft interrupt context + h : Hard interrupt context + H : Hard interrupt context which triggered during soft interrupt context. + z : NMI context + Z : NMI context which triggered during hard interrupt context + +Field 5 is the preemption count. + . : The preempt count is zero. + + On preemptible kernels (where the task can be scheduled out in + arbitrary locations while in kernel context), The preempt count, + when non zero, will prevent the kernel from scheduling out the + current task. The preempt count number is displayed when it is not + zero. +-- +Depending on the kernel, it may show other fields (lock depth, +or migration disabled, which are unique to specialized kernels). + +RETURN VALUE +------------ + +The _tep_is_latency_format()_ function returns true if "latency output" +is enabled, or false if it is disabled. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct trace_seq seq; +trace_seq_init(&seq); +... + tep_set_latency_format(tep, 1); +... + if (tep_is_latency_format(tep)) { + /* latency output format is enabled */ + } else { + /* latency output format is disabled */ + } +... +void process_record(struct tep_record *record) +{ + /* Write latency information in seq */ + tep_data_latency_format(tep, &seq, record); +} +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_, tep_print_event_task(3), +tep_print_event_time(3) + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:10 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898375 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 030321515 for ; Fri, 12 Apr 2019 13:38:43 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D7F9F28ED7 for ; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D4F9328EDD; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4F75728EDD for ; Fri, 12 Apr 2019 13:38:42 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726981AbfDLNim (ORCPT ); Fri, 12 Apr 2019 09:38:42 -0400 Received: from mail-wm1-f65.google.com ([209.85.128.65]:51545 "EHLO mail-wm1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726865AbfDLNim (ORCPT ); Fri, 12 Apr 2019 09:38:42 -0400 Received: by mail-wm1-f65.google.com with SMTP id 4so11294536wmf.1 for ; Fri, 12 Apr 2019 06:38:40 -0700 (PDT) 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=pPrLL331apy6OvFrsj5B67meH5BkpFyF8aPQL+p16+k=; b=dzN7mmDLxC0xnqTDsxtTflj9qTvQ74TR8mOQNHl/jdGwW9F5xuVVTJIOARfclPxstG mXhgKWo8odYuHpgN30OajpGgyce43aW8axPs7ZhG5oZaFiNrlqXZoA5ljxce3JM3hCkz 59qDaPO6ikH/K6qo65V3hWd9wfyo1u4DdKBS+V0sInatVgtc33s+llfhRtsAoz0u/ncE LMqmtzpcE8mKTT1eR1SV6rOJcPHxRKcfcSsiRhgKLf7M4pTrE8qDtxBJdmcjEeKlyBld aCfO8AYLevvNod+AuoZdMJHdcaLblsIjxMuMNZ27B1dS/leNM3ZD85EPLsEWl3NiRHrP 81qw== X-Gm-Message-State: APjAAAWRV1TF8miiL6ulSeG6UE4KO6k+jEOqat/OTivBzyMpdz+b69Js izpYdn95D16oc6F71RWRrWo= X-Google-Smtp-Source: APXvYqziCrvEt7+1z2v9Bo6QePzqJoZylrsZp3zR2UaLR9gTeHaKkw0KE6IhfvVcHMSQ4ze84rOSqg== X-Received: by 2002:a1c:a103:: with SMTP id k3mr11286832wme.8.1555076320143; Fri, 12 Apr 2019 06:38:40 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.39 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:39 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 29/30] tools/lib/traceevent: Man pages for APIs, used to extract common fields from a record Date: Fri, 12 Apr 2019 16:38:10 +0300 Message-Id: <20190412133811.15878-30-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for libtraceevent APIs: tep_data_type(), tep_data_pid(), tep_data_preempt_count(), tep_data_flags() Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-record_parse.txt | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt new file mode 100644 index 000000000000..1e1b38e03fa7 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt @@ -0,0 +1,137 @@ +libtraceevent(3) +================ + +NAME +---- +tep_data_type, tep_data_pid,tep_data_preempt_count, tep_data_flags - +Extract common fields from a record. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *trace_flag_type* { + _TRACE_FLAG_IRQS_OFF_, + _TRACE_FLAG_IRQS_NOSUPPOR_, + _TRACE_FLAG_NEED_RESCHED_, + _TRACE_FLAG_HARDIRQ_, + _TRACE_FLAG_SOFTIRQ_, +}; + +int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +-- + +DESCRIPTION +----------- +This set of functions can be used to extract common fields from a record. + +The _tep_data_type()_ function gets the event id from the record _rec_. +It reads the "common_type" field. The _tep_ argument is the trace event parser +context. + +The _tep_data_pid()_ function gets the process id from the record _rec_. +It reads the "common_pid" field. The _tep_ argument is the trace event parser +context. + +The _tep_data_preempt_count()_ function gets the preemption count from the +record _rec_. It reads the "common_preempt_count" field. The _tep_ argument is +the trace event parser context. + +The _tep_data_flags()_ function gets the latency flags from the record _rec_. +It reads the "common_flags" field. The _tep_ argument is the trace event parser +context. Supported latency flags are: +[verse] +-- + _TRACE_FLAG_IRQS_OFF_, Interrupts are disabled. + _TRACE_FLAG_IRQS_NOSUPPOR_, Reading IRQ flag is not supported by the architecture. + _TRACE_FLAG_NEED_RESCHED_, Task needs rescheduling. + _TRACE_FLAG_HARDIRQ_, Hard IRQ is running. + _TRACE_FLAG_SOFTIRQ_, Soft IRQ is running. +-- + +RETURN VALUE +------------ +The _tep_data_type()_ function returns an integer, representing the event id. + +The _tep_data_pid()_ function returns an integer, representing the process id + +The _tep_data_preempt_count()_ function returns an integer, representing the +preemption count. + +The _tep_data_flags()_ function returns an integer, representing the latency +flags. Look at the _trace_flag_type_ enum for supported flags. + +All these functions in case of an error return a negative integer. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void process_record(struct tep_record *record) +{ + int data; + + data = tep_data_type(tep, record); + if (data >= 0) { + /* Got the ID of the event */ + } + + data = tep_data_pid(tep, record); + if (data >= 0) { + /* Got the process ID */ + } + + data = tep_data_preempt_count(tep, record); + if (data >= 0) { + /* Got the preemption count */ + } + + data = tep_data_flags(tep, record); + if (data >= 0) { + /* Got the latency flags */ + } +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Apr 12 13:38:11 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10898377 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7DF45186E for ; Fri, 12 Apr 2019 13:38:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5CF6F28B44 for ; Fri, 12 Apr 2019 13:38:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5960C28DF2; Fri, 12 Apr 2019 13:38:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A838728EFC for ; Fri, 12 Apr 2019 13:38:43 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726865AbfDLNin (ORCPT ); Fri, 12 Apr 2019 09:38:43 -0400 Received: from mail-wr1-f67.google.com ([209.85.221.67]:44816 "EHLO mail-wr1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726965AbfDLNin (ORCPT ); Fri, 12 Apr 2019 09:38:43 -0400 Received: by mail-wr1-f67.google.com with SMTP id y7so11973006wrn.11 for ; Fri, 12 Apr 2019 06:38:41 -0700 (PDT) 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=1pyjYGzyAV1I6IQHXAb08su9TODg663ZbIYx4lSofPQ=; b=uYk76BvCG33Z7ELLy4WXK27gMxbSIv9ZNdZgFvyIbZnA4OQ1QfuU0B3NjFLgk/mbX2 qpl1ploLLjlfPWvsKBtN2RDXMiix6xaIS+XlnP9Vxj3EhOLkEIvKy3Lt+A1LMBICzico 85ct4mijZHOJ70aizAdmeojSDGhbIfBKtxjBn6Aq1yMqk8DSyNX+MqkBcT+9r52Zgfqp 3Mqy7B5S6uzFaKR6cwDcbJJEeYT1zV+06MP2lf7h9uPY8xvlpy3Bwx0btKSROwJt75mH rxqcjefIjiIvTpt5Wos120pBqyopobVqFz9oejBJMgPcGXWQwFzGoB7KEORaiaTk/QZM r1iQ== X-Gm-Message-State: APjAAAXu03hd3QDviROc+MvsQbyovdi12C4/wy8xbOb+J7hLbgOE37/f D0N8y9Nmp+7wEabG3Vc3iyHyECEs X-Google-Smtp-Source: APXvYqxAxFotcYWhu7V3qGgvRR36sUFLslA6FGH9cCkE5l20Uij4O1379N/zPSiiAynpStyfCW/cFQ== X-Received: by 2002:adf:ee07:: with SMTP id y7mr33622423wrn.219.1555076321020; Fri, 12 Apr 2019 06:38:41 -0700 (PDT) Received: from oberon.eng.vmware.com ([146.247.46.5]) by smtp.gmail.com with ESMTPSA id x205sm11594682wmg.9.2019.04.12.06.38.40 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 12 Apr 2019 06:38:40 -0700 (PDT) From: Tzvetomir Stoyanov To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v5 30/30] tools/lib/traceevent: Man pages for trace sequences APIs Date: Fri, 12 Apr 2019 16:38:11 +0300 Message-Id: <20190412133811.15878-31-tstoyanov@vmware.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190412133811.15878-1-tstoyanov@vmware.com> References: <20190412133811.15878-1-tstoyanov@vmware.com> MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Create man pages for trace sequences libtraceevent APIs: trace_seq_init(), trace_seq_destroy(), trace_seq_reset(), trace_seq_terminate(), trace_seq_putc(), trace_seq_puts(), trace_seq_printf(), trace_seq_vprintf(), trace_seq_do_fprintf(), trace_seq_do_printf() Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-tseq.txt | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt new file mode 100644 index 000000000000..8ac6aa174e12 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt @@ -0,0 +1,158 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_init, trace_seq_destroy, trace_seq_reset, trace_seq_terminate, +trace_seq_putc, trace_seq_puts, trace_seq_printf, trace_seq_vprintf, +trace_seq_do_fprintf, trace_seq_do_printf - +Initialize / destroy a trace sequence. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *trace_seq_init*(struct trace_seq pass:[*]_s_); +void *trace_seq_destroy*(struct trace_seq pass:[*]_s_); +void *trace_seq_reset*(struct trace_seq pass:[*]_s_); +void *trace_seq_terminate*(struct trace_seq pass:[*]_s_); +int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_); +int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_); +int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._); +int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_); +int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_); +int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_init()_ function initializes the trace sequence _s_. + +The _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees +all its resources that it had used. + +The _trace_seq_reset()_ function re-initializes the trace sequence _s_. All +characters already written in _s_ will be deleted. + +The _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts +the null character pass:['\0'] at the end of the buffer. + +The _trace_seq_putc()_ function puts a single character _c_ in the trace +sequence _s_. + +The _trace_seq_puts()_ function puts a NULL terminated string _str_ in the +trace sequence _s_. + +The _trace_seq_printf()_ function puts a formated string _fmt _with +variable arguments _..._ in the trace sequence _s_. + +The _trace_seq_vprintf()_ function puts a formated string _fmt _with +list of arguments _args_ in the trace sequence _s_. + +The _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to +the standard output stdout. + +The _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_ +to the given file _fp_. + +RETURN VALUE +------------ +Both _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of +characters put in the trace sequence, or 0 in case of an error + +Both _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return 0 if the +trace oversizes the buffer's free space, the number of characters printed, or +a negative value in case of an error. + +Both _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the +number of printed characters, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +void foo_seq_print(struct trace_seq *tseq, char *format, ...) +{ + va_list ap; + va_start(ap, format); + if (trace_seq_vprintf(tseq, format, ap) <= 0) { + /* Failed to print in the trace sequence */ + } + va_end(ap); +} + +trace_seq_reset(&seq); + +char *str = " MAN page example"; +if (trace_seq_puts(&seq, str) != strlen(str)) { + /* Failed to put str in the trace sequence */ +} +if (trace_seq_putc(&seq, ':') != 1) { + /* Failed to put ':' in the trace sequence */ +} +if (trace_seq_printf(&seq, " trace sequence: %d", 1) <= 0) { + /* Failed to print in the trace sequence */ +} +foo_seq_print( &seq, " %d\n", 2); + +trace_seq_terminate(&seq); +... + +if (trace_seq_do_printf(&seq) < 0 ) { + /* Failed to print the sequence buffer to the standard output */ +} +FILE *fp = fopen("trace.txt", "w"); +if (trace_seq_do_fprintf(&seq, fp) < 0 ) [ + /* Failed to print the sequence buffer to the trace.txt file */ +} + +trace_seq_destroy(&seq); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences related APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git