From patchwork Fri Apr 9 04:27:45 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tzvetomir Stoyanov (VMware)" X-Patchwork-Id: 12193013 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-20.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D9AD3C43460 for ; Fri, 9 Apr 2021 04:27:50 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B018C61168 for ; Fri, 9 Apr 2021 04:27:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229696AbhDIE2C (ORCPT ); Fri, 9 Apr 2021 00:28:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37508 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229498AbhDIE2C (ORCPT ); Fri, 9 Apr 2021 00:28:02 -0400 Received: from mail-ej1-x629.google.com (mail-ej1-x629.google.com [IPv6:2a00:1450:4864:20::629]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D4019C061760 for ; Thu, 8 Apr 2021 21:27:49 -0700 (PDT) Received: by mail-ej1-x629.google.com with SMTP id hq27so6509307ejc.9 for ; Thu, 08 Apr 2021 21:27:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=71dlf1XVvx7/yCFxV1DZr9CDIeVinmp3831/2FTao1w=; b=loIoj3I+EbL9rJ8r1qLPyuYXLJEpe1aZGJfo6NInuaJfz7oTWS5ch+pfQQtSj1mnoL 3fYJe7RMevXGtLhvR+ItRqsJuVwHM0+vwXP7C2v5pEoV3LTyGED/9QTuJLd6nSktceKX NiI8lnRQ80+64TvRX5GmXgbin4XxKpM1UKhvUg0PrEXePgD1g4tOe2uqCi+kTprrAjWm BRke85qVv21k+qNmXQfuSFbWcJjH+OwkG+E9yvcRjAOoGYP4PPzAKX+ATebDqBILHS9r IwdrgFCZ/3YZmeyWQO0JsgVI1GOTWXeCiVqKmkvDX+kRpkCX+llFWfsWZ/KWhLEzyhNJ njhQ== 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=71dlf1XVvx7/yCFxV1DZr9CDIeVinmp3831/2FTao1w=; b=i3kmNrpBJXyUEBSOsteqnlYioPIlgDEUr1yHD/3JJ183wFgJHCe0cu7KF6uH560vVA 2nUN3at2XQsvgYP3jkHgat4VXh8Prnnm/n9SqEOM2YT23abEC/6xmvHuWJLtpijCPXVR pFvFytKTT6oL/+y6giFe32ri+IBlAUFQONTpUYgZagGLJnxkUee3C2+AX9MEvpwMgHZU ZAvMyaGy/7hY0YtJkHN5Y48RWZ4MhwnYQkMMbXKgEEj7gft4lGS6Lgq0CWhgOcURLblO T4RU6TMXHQZL41BAdFl3U+yK14bRF9z9BeXDORSFd+ZqtvgMIG6rCOmljXr3DGQojSBF qxDQ== X-Gm-Message-State: AOAM530TAqdhbfOcuBdIFkG6ESN0pkIRXBy4aP+cAdInDuY85m/E25bZ u6jw1WXztyZDiQqtzkplPyM= X-Google-Smtp-Source: ABdhPJwTAtPnkiUTsw6QTEfe7hlXIwqhfmx0FVtan8ay6+e9LzoH5Ro5I7rJ6R6ywYQ3OimpLvtJrg== X-Received: by 2002:a17:906:c099:: with SMTP id f25mr14431149ejz.141.1617942468606; Thu, 08 Apr 2021 21:27:48 -0700 (PDT) Received: from oberon.zico.biz ([83.222.187.186]) by smtp.gmail.com with ESMTPSA id cf4sm701089edb.19.2021.04.08.21.27.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 08 Apr 2021 21:27:48 -0700 (PDT) From: "Tzvetomir Stoyanov (VMware)" To: rostedt@goodmis.org Cc: linux-trace-devel@vger.kernel.org Subject: [PATCH v2 1/2] libtracefs: Document marker APIs Date: Fri, 9 Apr 2021 07:27:45 +0300 Message-Id: <20210409042746.3179319-2-tz.stoyanov@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210409042746.3179319-1-tz.stoyanov@gmail.com> References: <20210409042746.3179319-1-tz.stoyanov@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org Added man pages describing these functions: tracefs_print_init(); tracefs_printf(); tracefs_vprintf(); tracefs_print_close(); tracefs_binary_init(); tracefs_binary_write(); tracefs_binary_close(); Signed-off-by: Tzvetomir Stoyanov (VMware) --- Documentation/libtracefs-marker.txt | 116 ++++++++++++++++++++++++ Documentation/libtracefs-marker_raw.txt | 102 +++++++++++++++++++++ Documentation/libtracefs.txt | 10 ++ 3 files changed, 228 insertions(+) create mode 100644 Documentation/libtracefs-marker.txt create mode 100644 Documentation/libtracefs-marker_raw.txt diff --git a/Documentation/libtracefs-marker.txt b/Documentation/libtracefs-marker.txt new file mode 100644 index 0000000..1905662 --- /dev/null +++ b/Documentation/libtracefs-marker.txt @@ -0,0 +1,116 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_print_init, tracefs_print_close, tracefs_printf, tracefs_vprintf - +Open, close and write formated strings in the trace buffer. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tracefs_print_init*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_printf*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_fmt_, _..._); +int *tracefs_vprintf*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_fmt_, va_list _ap_); +void *tracefs_print_close*(struct tracefs_instance pass:[*]_instance_); + +-- + +DESCRIPTION +----------- +Set of functions to write formated strings in the trace buffer. +See Documentation/trace/ftrace.rst from the Linux kernel tree for more information about writing +data from user space in the trace buffer. All these APIs have _instance_ as a first argument. If +NULL is passed as _instance_, the top trace instance is used. + +The _tracefs_print_init()_ function initializes the library for writing into the trace buffer of +the selected _instance_. It is not mandatory to call this API before writing strings, any of +the printf APIs will call it automatically, if the library is not yet initialized. But calling +_tracefs_print_init()_ in advance will speed up the writing. + +The _tracefs_printf()_ function writes a formatted string in the trace buffer of the selected +_instance_. The _fmt_ argument is a string in printf format, followed by variable arguments _..._. + +The _tracefs_vprintf()_ function writes a formatted string in the trace buffer of the selected +_instance_. The _fmt_ argument is a string in printf format, followed by list _ap_ of arguments. + +The _tracefs_print_close()_ function closes the resources, used by the library for writing in +the trace buffer of the selected instance. + +RETURN VALUE +------------ +The _tracefs_print_init()_, _tracefs_printf()_, and _tracefs_vprintf()_ functions return 0 if +the operation is successful, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include + +if (tracefs_print_init(NULL) < 0) { + /* Failed to initialize the library for writing in the trace buffer of the top trace instance */ +} + +void foo_print(char *format, ...) +{ + va_list ap; + va_start(ap, format); + if (tracefs_vprintf(NULL, format, ap) < 0) { + /* Failed to print in the trace buffer */ + } + va_end(ap); +} + +void foo_print_string(char *message) +{ + if (tracefs_printf(NULL, "Message from user space: %s", message) < 0) { + /* Failed to print in the trace buffer */ + } +} + +tracefs_print_close(); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_, +Documentation/trace/ftrace.rst from the Linux kernel tree + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ + +COPYING +------- +Copyright \(C) 2021 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracefs-marker_raw.txt b/Documentation/libtracefs-marker_raw.txt new file mode 100644 index 0000000..f53ac72 --- /dev/null +++ b/Documentation/libtracefs-marker_raw.txt @@ -0,0 +1,102 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_binary_init, tracefs_binary_close, tracefs_binary_write - +Open, close and write binary data in the trace buffer. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tracefs_binary_init*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_binary_write*(struct tracefs_instance pass:[*]_instance_, void pass:[*]_data_, int _len_); +void *tracefs_binary_close*(struct tracefs_instance pass:[*]_instance_); + +-- + +DESCRIPTION +----------- +Set of functions to write binary data in the trace buffer. +See Documentation/trace/ftrace.rst from the Linux kernel tree for more information about writing +data from user space in the trace buffer. All these APIs have _instance_ as a first argument. If +NULL is passed as _instance_, the top trace instance is used. + +The _tracefs_binary_init()_ function initializes the library for writing into the trace buffer of +the selected _instance_. It is not mandatory to call this API before writing data, the +_tracefs_binary_write()_ will call it automatically, if the library is not yet initialized. +But calling _tracefs_binary_init()_ in advance will speed up the writing. + +The _tracefs_binary_write()_ function writes a binary data in the trace buffer of the selected +_instance_. The _data_ points to the data with length _len_, that is going to be written in +the trace buffer. + +The _tracefs_binary_close()_ function closes the resources, used by the library for writing in +the trace buffer of the selected instance. + +RETURN VALUE +------------ +The _tracefs_binary_init()_, and _tracefs_binary_write()_ functions return 0 if the operation is +successful, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include + +if (tracefs_binary_init(NULL) < 0) { + /* Failed to initialize the library for writing in the trace buffer of the top trace instance */ +} + +unsigned int data = 0xdeadbeef; + + if (tracefs_binary_write(NULL, &data, sizeof(data)) < 0) { + /* Failed to write in the trace buffer */ + } + +tracefs_binary_close(); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_, +Documentation/trace/ftrace.rst from the Linux kernel tree + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ + +COPYING +------- +Copyright \(C) 2021 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt index cea21fe..77d053d 100644 --- a/Documentation/libtracefs.txt +++ b/Documentation/libtracefs.txt @@ -51,6 +51,16 @@ Trace helper functions: int _tracefs_trace_on_get_fd_(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on_fd*(int _fd_); int *tracefs_trace_off_fd*(int _fd_); + +Writing data in the trace buffer: + int *tracefs_print_init*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_printf*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_fmt_, _..._); + int *tracefs_vprintf*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_fmt_, va_list _ap_); + void *tracefs_print_close*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_binary_init*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_binary_write*(struct tracefs_instance pass:[*]_instance_, void pass:[*]_data_, int _len_); + void *tracefs_binary_close*(struct tracefs_instance pass:[*]_instance_); + -- DESCRIPTION