From patchwork Thu Sep 22 00:29:36 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 12984335 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 192BEC6FA92 for ; Thu, 22 Sep 2022 00:28:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229522AbiIVA2q (ORCPT ); Wed, 21 Sep 2022 20:28:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38718 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229604AbiIVA2o (ORCPT ); Wed, 21 Sep 2022 20:28:44 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7ACE5A9255 for ; Wed, 21 Sep 2022 17:28:42 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 08ED4B83375 for ; Thu, 22 Sep 2022 00:28:41 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2262EC433C1; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.96) (envelope-from ) id 1obA61-00Dr5B-09; Wed, 21 Sep 2022 20:29:41 -0400 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: "Steven Rostedt (Google)" Subject: [PATCH 1/5] tracecmd library documentation: Use star and not underscore for function names Date: Wed, 21 Sep 2022 20:29:36 -0400 Message-Id: <20220922002940.3302285-2-rostedt@goodmis.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220922002940.3302285-1-rostedt@goodmis.org> References: <20220922002940.3302285-1-rostedt@goodmis.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org From: "Steven Rostedt (Google)" Functions referenced in man pages should be bold and not underscored. Convert all function references in the man pages to be bold. Signed-off-by: Steven Rostedt (Google) --- .../libtracecmd/libtracecmd-files.txt | 38 +++++++++---------- .../libtracecmd/libtracecmd-instances.txt | 32 ++++++++-------- Documentation/libtracecmd/libtracecmd-log.txt | 12 +++--- .../libtracecmd/libtracecmd-peer.txt | 16 ++++---- .../libtracecmd/libtracecmd-record.txt | 36 +++++++++--------- Documentation/libtracecmd/libtracecmd.txt | 8 ++-- 6 files changed, 71 insertions(+), 71 deletions(-) diff --git a/Documentation/libtracecmd/libtracecmd-files.txt b/Documentation/libtracecmd/libtracecmd-files.txt index 2de5d6dfa660..382603efd50d 100644 --- a/Documentation/libtracecmd/libtracecmd-files.txt +++ b/Documentation/libtracecmd/libtracecmd-files.txt @@ -22,7 +22,7 @@ void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); DESCRIPTION ----------- This set of APIs can be used to open and close a trace file recorded by -_trace-cmd(1)_ and containing tracing information from ftrace, the official +*trace-cmd(1)* and containing tracing information from ftrace, the official Linux kernel tracer. The opened file is represented by a _tracecmd_input_ structure, all other library APIs that work with the file require a pointer to the structure. The APIs for opening a trace file have a _flag_ input @@ -33,37 +33,37 @@ is a combination of these options: TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only" plugins from user's home directory. -The _tracecmd_open()_ function opens a given trace _file_, parses the +The *tracecmd_open()* function opens a given trace _file_, parses the metadata headers from the file, allocates and initializes а _tracecmd_input_ handler structure representing the file. It also initializes the handler for reading trace data from the file. The returned handler is ready to be used with _tracecmd_read__ APIs. -The _tracecmd_open_fd()_ function does the same as _tracecmd_open()_, but +The *tracecmd_open_fd()* function does the same as *tracecmd_open()*, but works with a file descriptor to a trace file, opened for reading. -The _tracecmd_open_head()_ function is the same as _tracecmd_open()_, but +The *tracecmd_open_head()* function is the same as *tracecmd_open()*, but does not initialize the handler for reading trace data. It reads and parses -the metadata headers only. The _tracecmd_init_data()_ should be used before +the metadata headers only. The *tracecmd_init_data()* should be used before using the _tracecmd_read__ APIs. -The _tracecmd_init_data()_ function initializes a _handle_, allocated with -_tracecmd_open_head()_, for reading trace data from the file associated with +The *tracecmd_init_data()* function initializes a _handle_, allocated with +*tracecmd_open_head()*, for reading trace data from the file associated with it. This API must be called before any of the _tracecmd_read__ APIs. -The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input -structure, previously allocated with _tracecmd_open()_, _tracecmd_open_fd()_ -or _tracecmd_open_head()_ APIs. +The *tracecmd_close()* function frees a _handle_, pointer to tracecmd_input +structure, previously allocated with *tracecmd_open()*, *tracecmd_open_fd()* +or *tracecmd_open_head()* APIs. RETURN VALUE ------------ -The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_ +The *tracecmd_open()*, *tracecmd_open_fd()* and *tracecmd_open_head()* functions return a pointer to tracecmd_input structure or NULL in case of -an error. The returned structure must be free with _tracecmd_close()_. -Note that if _tracecmd_open_fd()_ is used to allocate a tracecmd_input handler, -when _tracecmd_close()_ is called to close it, that fd will be closed also. +an error. The returned structure must be free with *tracecmd_close()*. +Note that if *tracecmd_open_fd()* is used to allocate a tracecmd_input handler, +when *tracecmd_close()* is called to close it, that fd will be closed also. -The _tracecmd_init_data()_ function returns -1 in case of an error or +The *tracecmd_init_data()* function returns -1 in case of an error or 0 otherwise. EXAMPLE @@ -139,10 +139,10 @@ FILES SEE ALSO -------- -_libtracefs(3)_, -_libtraceevent(3)_, -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtracefs(3)*, +*libtraceevent(3)*, +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ diff --git a/Documentation/libtracecmd/libtracecmd-instances.txt b/Documentation/libtracecmd/libtracecmd-instances.txt index df8fdc4e7f66..364085fdf482 100644 --- a/Documentation/libtracecmd/libtracecmd-instances.txt +++ b/Documentation/libtracecmd/libtracecmd-instances.txt @@ -22,36 +22,36 @@ DESCRIPTION This set of APIs can be used to get information and read tracing data from tracing instances stored in a trace file. -The _tracecmd_buffer_instances()_ function gets the number of tracing +The *tracecmd_buffer_instances()* function gets the number of tracing instances recorded in a trace file. The top instance is not counted. The _handle_ is a tracecmd_input handler returned by -_tracecmd_open_head()_. +*tracecmd_open_head()*. -The _tracecmd_buffer_instance_name()_ function gets the name of the +The *tracecmd_buffer_instance_name()* function gets the name of the tracing instance with given index _indx_, recorded in a trace file. The _indx_ is a number in the interval [0 .. count-1], where count -is the number returned by _tracecmd_buffer_instances()_. The _handle_ -is a tracecmd_input handler returned by _tracecmd_open_head()_. +is the number returned by *tracecmd_buffer_instances()*. The _handle_ +is a tracecmd_input handler returned by *tracecmd_open_head()*. -The _tracecmd_buffer_instance_handle()_ allocates and initializes a +The *tracecmd_buffer_instance_handle()* allocates and initializes a tracecmd_input handle, associated with trace instance with index _indx_ from a trace file. The _handle_ is a tracecmd_input handler -returned by _tracecmd_open_head()_. The _indx_ is a number in the +returned by *tracecmd_open_head()*. The _indx_ is a number in the interval [0 .. count-1], where count is the number returned by -_tracecmd_buffer_instances()_. +*tracecmd_buffer_instances()*. RETURN VALUE ------------ -The _tracecmd_buffer_instances()_ function returns the number of tracing +The *tracecmd_buffer_instances()* function returns the number of tracing instances recorded in a trace file. -The _tracecmd_buffer_instance_name()_ function returns a string, the name +The *tracecmd_buffer_instance_name()* function returns a string, the name of a tracing instance, or NULL in case of an error The string must *not* be freed. -The _tracecmd_buffer_instance_handle()_ function returns a pointer to +The *tracecmd_buffer_instance_handle()* function returns a pointer to newly allocated tracecmd_input handler or NULL in case if an error. The -returned handler must be closed by _tracecmd_close()(3)_ +returned handler must be closed by *tracecmd_close()(3)* EXAMPLE ------- @@ -99,10 +99,10 @@ FILES SEE ALSO -------- -_libtracefs(3)_, -_libtraceevent(3)_, -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtracefs(3)*, +*libtraceevent(3)*, +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ diff --git a/Documentation/libtracecmd/libtracecmd-log.txt b/Documentation/libtracecmd/libtracecmd-log.txt index de5c277684ec..38e17bf744ff 100644 --- a/Documentation/libtracecmd/libtracecmd-log.txt +++ b/Documentation/libtracecmd/libtracecmd-log.txt @@ -16,8 +16,8 @@ int *tracecmd_set_loglevel*(enum tep_loglevel _level_); DESCRIPTION ----------- -The _tracecmd_set_loglevel()_ function sets the level of the library logs that will be printed on -the console. See _libtraceevent(3)_ for detailed desciription of the log levels. Setting the log +The *tracecmd_set_loglevel()* function sets the level of the library logs that will be printed on +the console. See *libtraceevent(3)* for detailed desciription of the log levels. Setting the log level to specific value means that logs from the previous levels will be printed too. For example _TEP_LOG_WARNING_ will print any logs with severity _TEP_LOG_WARNING_, _TEP_LOG_ERROR_ and _TEP_LOG_CRITICAL_. The default log level is _TEP_LOG_CRITICAL_. When a new level is set, it is @@ -48,10 +48,10 @@ FILES SEE ALSO -------- -_libtracefs(3)_, -_libtraceevent(3)_, -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtracefs(3)*, +*libtraceevent(3)*, +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ diff --git a/Documentation/libtracecmd/libtracecmd-peer.txt b/Documentation/libtracecmd/libtracecmd-peer.txt index 2e3232c6edb5..c9774c86945a 100644 --- a/Documentation/libtracecmd/libtracecmd-peer.txt +++ b/Documentation/libtracecmd/libtracecmd-peer.txt @@ -25,13 +25,13 @@ Information about peers from the session is stored in the metadata of each trace file. These APIs use that information to extract and synchronize the trace data. -The _tracecmd_get_traceid()_ function returns the trace ID stored in +The *tracecmd_get_traceid()* function returns the trace ID stored in the trace file metadata associated with _handle_. Each peer from a trace session has an ID unique for that peer and that trace session only. This ID is used to match multiple trace files recorded in a same trace session. -The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest +The *tracecmd_get_guest_cpumap()* function gets the mapping of guest virtual CPUs (VCPU) to the host process that represents those VCPUs and is stored in the metadata of the trace file associated with _handle_. This information is gathered during a host-guest trace session and is stored @@ -47,9 +47,9 @@ The _name_, _vcpu_count_ and _cpu_pid_ values must *not* be freed. RETURN VALUE ------------ -The _tracecmd_get_traceid()_ function returns a 64 bit trace ID. +The *tracecmd_get_traceid()* function returns a 64 bit trace ID. -The _tracecmd_get_guest_cpumap()_ function returns -1 in case of +The *tracecmd_get_guest_cpumap()* function returns -1 in case of an error or 0 otherwise. If 0 is returned, then the _name_, _vcpu_count_ and _cpu_pid_ parameters contain the requested information. @@ -107,10 +107,10 @@ FILES SEE ALSO -------- -_libtracefs(3)_, -_libtraceevent(3)_, -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtracefs(3)*, +*libtraceevent(3)*, +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ diff --git a/Documentation/libtracecmd/libtracecmd-record.txt b/Documentation/libtracecmd/libtracecmd-record.txt index aa1a4a662929..69439552d6ba 100644 --- a/Documentation/libtracecmd/libtracecmd-record.txt +++ b/Documentation/libtracecmd/libtracecmd-record.txt @@ -22,38 +22,38 @@ struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_hand DESCRIPTION ----------- This set of APIs can be used to read tracing data from a trace file opened -with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_. +with *tracecmd_open()(3)*, *tracecmd_open_fd()(3)* or *tracecmd_open_head()(3)*. -The _tracecmd_read_cpu_first()_ function reads the first trace record +The *tracecmd_read_cpu_first()* function reads the first trace record for a given _cpu_ from a trace file associated with _handle_. The returned -record must be freed with _tracecmd_free_record()_. +record must be freed with *tracecmd_free_record()*. -The _tracecmd_read_data()_ function reads the next trace record for +The *tracecmd_read_data()* function reads the next trace record for a given _cpu_ from a trace file associated with _handle_ and increments -the read location pointer, so that the next call to _tracecmd_read_data()_ +the read location pointer, so that the next call to *tracecmd_read_data()* will not read the same record again. The returned record must be freed -with _tracecmd_free_record()_. +with *tracecmd_free_record()*. -The _tracecmd_read_at()_ function reads a trace record from a specific +The *tracecmd_read_at()* function reads a trace record from a specific _offset_ within the file associated with _handle_. The CPU on which the recorded event occurred is stored in the _cpu_. The function does not change the current read location pointer. The returned record must be -freed with _tracecmd_free_record()_. +freed with *tracecmd_free_record()*. -The _tracecmd_free_record()_ function frees a _record_ returned by any +The *tracecmd_free_record()* function frees a _record_ returned by any of the _tracecmd_read__ APIs. -The _tracecmd_get_tep()_ function returns a tep context for a given +The *tracecmd_get_tep()* function returns a tep context for a given _handle_. RETURN VALUE ------------ -The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and -_tracecmd_read_at()_ functions return a pointer to struct tep_record or +The *tracecmd_read_cpu_first()*, *tracecmd_read_data()* and +*tracecmd_read_at()* functions return a pointer to struct tep_record or NULL in case of an error.The returned record must be freed with -_tracecmd_free_record()_. +*tracecmd_free_record()*. -The _tracecmd_get_tep()_ function returns a pointer to tep context or +The *tracecmd_get_tep()* function returns a pointer to tep context or NULL if there is no tep context for the given _handle_. The returned tep pointer must *not* be freed. @@ -108,10 +108,10 @@ FILES SEE ALSO -------- -_libtracefs(3)_, -_libtraceevent(3)_, -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtracefs(3)*, +*libtraceevent(3)*, +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt index dc528ce02aac..e9e11b32c8b6 100644 --- a/Documentation/libtracecmd/libtracecmd.txt +++ b/Documentation/libtracecmd/libtracecmd.txt @@ -56,10 +56,10 @@ FILES SEE ALSO -------- -_libtraceevent(3)_ -_libtracefs(3)_ -_trace-cmd(1)_ -_trace-cmd.dat(5)_ +*libtraceevent(3)* +*libtracefs(3)* +*trace-cmd(1)* +*trace-cmd.dat(5)* AUTHOR ------ From patchwork Thu Sep 22 00:29:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 12984331 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1DBE8C6FA8E for ; Thu, 22 Sep 2022 00:28:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229658AbiIVA2n (ORCPT ); Wed, 21 Sep 2022 20:28:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38698 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229522AbiIVA2m (ORCPT ); Wed, 21 Sep 2022 20:28:42 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B1F13A9267 for ; Wed, 21 Sep 2022 17:28:41 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 65775B82856 for ; Thu, 22 Sep 2022 00:28:40 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 28C8FC433B5; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.96) (envelope-from ) id 1obA61-00Dr5E-0D; Wed, 21 Sep 2022 20:29:41 -0400 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: "Steven Rostedt (Google)" Subject: [PATCH 2/5] trace-cmd library: Make tracecmd_filter_match() local Date: Wed, 21 Sep 2022 20:29:37 -0400 Message-Id: <20220922002940.3302285-3-rostedt@goodmis.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220922002940.3302285-1-rostedt@goodmis.org> References: <20220922002940.3302285-1-rostedt@goodmis.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org From: "Steven Rostedt (Google)" The function tracecmd_filter_match() is really an internal function. It should not be exported for other applications (The trace-cmd core functions do not use it). It should definitely not be in the public headers. Move the prototype so that it is only used internally within the library. Signed-off-by: Steven Rostedt (Google) --- include/trace-cmd/trace-cmd.h | 2 -- lib/trace-cmd/include/trace-cmd-local.h | 3 +++ lib/trace-cmd/trace-filter.c | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/include/trace-cmd/trace-cmd.h b/include/trace-cmd/trace-cmd.h index 4963f45dfe12..331815b9edc2 100644 --- a/include/trace-cmd/trace-cmd.h +++ b/include/trace-cmd/trace-cmd.h @@ -76,7 +76,5 @@ enum tracecmd_filters { struct tracecmd_filter; struct tracecmd_filter *tracecmd_filter_add(struct tracecmd_input *handle, const char *filter_str, bool neg); -enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter, - struct tep_record *record); #endif /* _TRACE_CMD_H */ diff --git a/lib/trace-cmd/include/trace-cmd-local.h b/lib/trace-cmd/include/trace-cmd-local.h index 2a458133204b..c95ec6530fdd 100644 --- a/lib/trace-cmd/include/trace-cmd-local.h +++ b/lib/trace-cmd/include/trace-cmd-local.h @@ -49,6 +49,9 @@ struct data_file_write { unsigned long long file_data_offset; }; +enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter, + struct tep_record *record); + void tracecmd_compress_init(void); void tracecmd_compress_free(void); diff --git a/lib/trace-cmd/trace-filter.c b/lib/trace-cmd/trace-filter.c index f7eb46c762d6..1c8c07fcf0da 100644 --- a/lib/trace-cmd/trace-filter.c +++ b/lib/trace-cmd/trace-filter.c @@ -44,8 +44,8 @@ static bool test_stacktraces(struct tracecmd_filter *filter, struct tep_record * test_stacktrace(filter, record, filter->user_stacktrace_id); } -enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter, - struct tep_record *record) +__hidden enum tracecmd_filters tracecmd_filter_match(struct tracecmd_filter *filter, + struct tep_record *record) { bool found = false; int ret; From patchwork Thu Sep 22 00:29:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 12984330 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F19F3ECAAD8 for ; Thu, 22 Sep 2022 00:28:43 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229738AbiIVA2m (ORCPT ); Wed, 21 Sep 2022 20:28:42 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38704 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229658AbiIVA2k (ORCPT ); Wed, 21 Sep 2022 20:28:40 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1F943A9255 for ; Wed, 21 Sep 2022 17:28:40 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id AFC3B62985 for ; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 263A4C433D7; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.96) (envelope-from ) id 1obA61-00Dr5H-0H; Wed, 21 Sep 2022 20:29:41 -0400 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: "Steven Rostedt (Google)" Subject: [PATCH 3/5] libtracecmd: Add check-manpages.sh Date: Wed, 21 Sep 2022 20:29:38 -0400 Message-Id: <20220922002940.3302285-4-rostedt@goodmis.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220922002940.3302285-1-rostedt@goodmis.org> References: <20220922002940.3302285-1-rostedt@goodmis.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org From: "Steven Rostedt (Google)" Add the script check-manpages.sh that makes sure all the function that are documented in the man pages are show in the overall man page "libtracecmd" as well as making sure that all functions in trace-cmd.h is also documented. Signed-off-by: Steven Rostedt (Google) --- Makefile | 5 ++++- check-manpages.sh | 54 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100755 check-manpages.sh diff --git a/Makefile b/Makefile index 7178d7a9758d..f0c7938b6908 100644 --- a/Makefile +++ b/Makefile @@ -508,7 +508,7 @@ install_gui: force install_libs: libs $(Q)$(MAKE) -C $(src)/lib/trace-cmd/ $@ -doc: +doc: check_doc $(MAKE) -C $(src)/Documentation all doc_clean: @@ -517,6 +517,9 @@ doc_clean: install_doc: $(MAKE) -C $(src)/Documentation install +check_doc: force + $(Q)$(src)/check-manpages.sh $(src)/Documentation/libtracecmd + clean: $(RM) *.o *~ *.a *.so .*.d $(RM) tags TAGS cscope* $(PKG_CONFIG_SOURCE_FILE) $(VERSION_FILE) diff --git a/check-manpages.sh b/check-manpages.sh new file mode 100755 index 000000000000..1166bbe82cad --- /dev/null +++ b/check-manpages.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# SPDX-License-Identifier: LGPL-2.1 +# Copyright (C) 2022, Google Inc, Steven Rostedt +# +# This checks if any function is listed in a man page that is not listed +# in the main man page. + +if [ $# -lt 1 ]; then + echo "usage: check-manpages man-page-path" + exit 1 +fi + +cd $1 + +MAIN=libtracecmd +MAIN_FILE=${MAIN}.txt + +# Ignore man pages that do not contain functions +IGNORE="" + +for man in ${MAIN}-*.txt; do + + sed -ne '/^NAME/,/^SYNOP/{/^[a-z]/{s/, *$//;s/,/\n/g;s/ //g;s/-.*$/-/;/-/{s/-//p;q};p}}' $man | while read a; do + if [ "${IGNORE/$man/}" != "${IGNORE}" ]; then + continue + fi + if ! grep -q '\*'${a}'\*' $MAIN_FILE; then + if [ "$last" == "" ]; then + echo + fi + if [ "$last" != "$man" ]; then + echo "Missing functions from $MAIN_FILE that are in $man" + last=$man + fi + echo " ${a}" + fi + done +done + +DEPRECATED="" + +sed -ne 's/^[a-z].*[ \*]\([a-z_][a-z_]*\)(.*/\1/p' -e 's/^\([a-z_][a-z_]*\)(.*/\1/p' ../../include/trace-cmd/trace-cmd.h | while read f; do + if ! grep -q '\*'${f}'\*' $MAIN_FILE; then + if [ "${DEPRECATED/\*$f\*/}" != "${DEPRECATED}" ]; then + continue; + fi + if [ "$last" == "" ]; then + echo + echo "Missing functions from $MAIN_FILE that are in tracefs.h" + last=$f + fi + echo " ${f}" + fi +done From patchwork Thu Sep 22 00:29:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 12984333 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0CB11C6FA91 for ; Thu, 22 Sep 2022 00:28:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229731AbiIVA2p (ORCPT ); Wed, 21 Sep 2022 20:28:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38748 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229716AbiIVA2n (ORCPT ); Wed, 21 Sep 2022 20:28:43 -0400 Received: from ams.source.kernel.org (ams.source.kernel.org [145.40.68.75]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CF1F1A926E for ; Wed, 21 Sep 2022 17:28:41 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 6B90FB83344 for ; Thu, 22 Sep 2022 00:28:40 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2B55DC433D6; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.96) (envelope-from ) id 1obA61-00Dr5K-0L; Wed, 21 Sep 2022 20:29:41 -0400 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: "Steven Rostedt (Google)" Subject: [PATCH 4/5] libtracecmd: Add a man pages for handling of time stamps Date: Wed, 21 Sep 2022 20:29:39 -0400 Message-Id: <20220922002940.3302285-5-rostedt@goodmis.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220922002940.3302285-1-rostedt@goodmis.org> References: <20220922002940.3302285-1-rostedt@goodmis.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org From: "Steven Rostedt (Google)" Add to the man pages the function tracecmd_get_first_ts(), and tracecmd_add_ts_offset(). Signed-off-by: Steven Rostedt (Google) --- .../libtracecmd/libtracecmd-timestamp.txt | 138 ++++++++++++++++++ Documentation/libtracecmd/libtracecmd.txt | 4 + 2 files changed, 142 insertions(+) create mode 100644 Documentation/libtracecmd/libtracecmd-timestamp.txt diff --git a/Documentation/libtracecmd/libtracecmd-timestamp.txt b/Documentation/libtracecmd/libtracecmd-timestamp.txt new file mode 100644 index 000000000000..8695d003965b --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-timestamp.txt @@ -0,0 +1,138 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_get_first_ts, tracecmd_add_ts_offset - Handle time stamps from a trace file. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +unsigned long long *tracecmd_get_first_ts*(struct tracecmd_input pass:[*]_handle_); +void *tracecmd_add_ts_offset*(struct tracecmd_input pass:[*]_handle_, long long _offset_); +-- + +DESCRIPTION +----------- +This set of APIs can be used to read tracing data from a trace file opened +with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_. + +The *tracecmd_get_first_ts()* function returns the time stamp of the first +record in the _handle_. + +The *tracecmd_add_ts_offset()* function adds an offset to each of the records +in the _handle_ that represents a trace file. This is useful for associating two +different tracing files by their offset (for example a trace file from a host +and a trace file from a guest that were not synchronized when created). + +RETURN VALUE +------------ +The *tracecmd_get_first_ts()* function returns the timestamp of the first +record in a trace file for the given _handle_. + +EXAMPLE +------- +[source,c] +-- +#include +#include + +static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data) +{ + static struct trace_seq seq; + struct tep_handle *tep = tracecmd_get_tep(handle); + const char *file = tracecmd_get_private(handle); + + if (!seq.buffer) + trace_seq_init(&seq); + + trace_seq_reset(&seq); + trace_seq_printf(&seq, "%s: ", file); + tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n", + TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID, + TEP_PRINT_NAME, TEP_PRINT_INFO); + trace_seq_terminate(&seq); + trace_seq_do_printf(&seq); + return 0; +} + +int main(int argc, char **argv) +{ + struct tracecmd_input **handles = NULL; + unsigned long long ts, first_ts = 0; + int nr_handles = 0; + int i; + + if (argc < 2) { + printf("usage: %s trace.dat [trace.dat ...]\n", argv[0]); + exit(-1); + } + + for (i = 1; i < argc; i++) { + handles = realloc(handles, sizeof(*handles) * (nr_handles + 1)); + if (!handles) + exit(-1); + handles[nr_handles] = tracecmd_open(argv[i], 0); + if (!handles[nr_handles]) + exit(-1); + tracecmd_set_private(handles[nr_handles], argv[i]); + ts = tracecmd_get_first_ts(handles[nr_handles]); + if (!first_ts || ts < first_ts) + first_ts = ts; + nr_handles++; + } + + /* Set the time stamp to start at the first record found */ + for (i = 0; i < nr_handles; i++) + tracecmd_add_ts_offset(handles[i], -first_ts); + + tracecmd_iterate_events_multi(handles, nr_handles, print_events, NULL); + + for (i = 0; i < nr_handles; i++) + tracecmd_close(handles[i]); + free(handles); +} +-- +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* +*Tzvetomir Stoyanov* +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt index e9e11b32c8b6..1939c209dc34 100644 --- a/Documentation/libtracecmd/libtracecmd.txt +++ b/Documentation/libtracecmd/libtracecmd.txt @@ -30,6 +30,10 @@ Read tracing instances from a trace file: const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_); struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_); +Handle time stamps from a trace file: + unsigned long long *tracecmd_get_first_ts*(struct tracecmd_input pass:[*]_handle_); + void *tracecmd_add_ts_offset*(struct tracecmd_input pass:[*]_handle_, long long _offset_); + Get traceing peer information from a trace file: unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_); int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_); From patchwork Thu Sep 22 00:29:40 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 12984334 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AD214C32771 for ; Thu, 22 Sep 2022 00:28:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229822AbiIVA2p (ORCPT ); Wed, 21 Sep 2022 20:28:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38722 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229522AbiIVA2o (ORCPT ); Wed, 21 Sep 2022 20:28:44 -0400 Received: from sin.source.kernel.org (sin.source.kernel.org [IPv6:2604:1380:40e1:4800::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D2CFB9FA98 for ; Wed, 21 Sep 2022 17:28:42 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 19308CE1EF4 for ; Thu, 22 Sep 2022 00:28:41 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4DFD4C43470; Thu, 22 Sep 2022 00:28:39 +0000 (UTC) Received: from rostedt by gandalf.local.home with local (Exim 4.96) (envelope-from ) id 1obA61-00Dr5N-0P; Wed, 21 Sep 2022 20:29:41 -0400 From: Steven Rostedt To: linux-trace-devel@vger.kernel.org Cc: "Steven Rostedt (Google)" Subject: [PATCH 5/5] libtracecmd: Add documentation on tracecmd_set/get_private() Date: Wed, 21 Sep 2022 20:29:40 -0400 Message-Id: <20220922002940.3302285-6-rostedt@goodmis.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220922002940.3302285-1-rostedt@goodmis.org> References: <20220922002940.3302285-1-rostedt@goodmis.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-trace-devel@vger.kernel.org From: "Steven Rostedt (Google)" The tracecmd_set_private() and tracecmd_get_private() functions were not in the man pages. Add them, and also add a working example for the tracecmd_open() (and other) function. Signed-off-by: Steven Rostedt (Google) --- .../libtracecmd/libtracecmd-files.txt | 72 ++++++++++++------- Documentation/libtracecmd/libtracecmd.txt | 2 + 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/Documentation/libtracecmd/libtracecmd-files.txt b/Documentation/libtracecmd/libtracecmd-files.txt index 382603efd50d..f8292cb4cbd5 100644 --- a/Documentation/libtracecmd/libtracecmd-files.txt +++ b/Documentation/libtracecmd/libtracecmd-files.txt @@ -4,7 +4,7 @@ libtracecmd(3) NAME ---- tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data, -tracecmd_close - Open and close a trace file. +tracecmd_close, tracecmd_set_private, tracecmd_get_private - Open and close a trace file. SYNOPSIS -------- @@ -17,6 +17,8 @@ struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_); struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_); int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_); void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); +void *tracecmd_set_private*(struct tracecmd_input pass:[*]_handle_, void pass:[*]_data_); +void pass:[*]*tracecmd_get_private*(struct tracecmd_input pass:[*]_handle_); -- DESCRIPTION @@ -55,6 +57,12 @@ The *tracecmd_close()* function frees a _handle_, pointer to tracecmd_input structure, previously allocated with *tracecmd_open()*, *tracecmd_open_fd()* or *tracecmd_open_head()* APIs. +The *tracecmd_set_private()* function allows to add specific _data_ to the +_handle_ that can be retrieved later. + +The *tracecmd_get_private()* function will retrieve the _data_ set by +*tracecmd_set_private()* for the given _handle_. + RETURN VALUE ------------ The *tracecmd_open()*, *tracecmd_open_fd()* and *tracecmd_open_head()* @@ -66,6 +74,8 @@ when *tracecmd_close()* is called to close it, that fd will be closed also. The *tracecmd_init_data()* function returns -1 in case of an error or 0 otherwise. +The *tracecmd_get_private()* returns the _data_ set by *tracecmd_set_private()*. + EXAMPLE ------- [source,c] @@ -75,32 +85,46 @@ a trace file, which can be used depending on the use case. 1. Open and initialise the trace file in а single step: +#include #include -... -struct tracecmd_input *handle = tracecmd_open("trace.dat"); - if (!handle) { - /* Failed to open trace.dat file */ - } -... - /* Read tracing data from the file, using the handle */ -... - tracecmd_close(handle); -... -int fd; - fd = = open("trace.dat", O_RDONLY); - if (fd < 0) { - /* Failed to open trace file for reading */ - } - handle = tracecmd_open_fd(fd); - if (!handle) { - close(fd); - /* Failed to initialise handler for reading the trace file */ + +static int print_events(struct tracecmd_input *handle, struct tep_record *record, int cpu, void *data) +{ + static struct trace_seq seq; + struct tep_handle *tep = tracecmd_get_tep(handle); + const char *file = tracecmd_get_private(handle); + + if (!seq.buffer) + trace_seq_init(&seq); + + trace_seq_reset(&seq); + trace_seq_printf(&seq, "%s: ", file); + tep_print_event(tep, &seq, record, "%6.1000d [%03d] %s-%d %s: %s\n", + TEP_PRINT_TIME, TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID, + TEP_PRINT_NAME, TEP_PRINT_INFO); + trace_seq_terminate(&seq); + trace_seq_do_printf(&seq); + return 0; +} + +int main(int argc, char **argv) +{ + struct tracecmd_input *handle; + + if (argc < 2) { + printf("usage: %s trace.dat\n", argv[0]); + exit(-1); } -... - /* Read tracing data from the file, using the handle */ -... + + handle = tracecmd_open(argv[i], 0); + if (!handle) + exit(-1); + + tracecmd_set_private(handles[nr_handles], argv[i]); + tracecmd_iterate_events(handles, NULL, 0, print_events, NULL); + tracecmd_close(handle); -... +} 2. Open and initialise the trace file in two steps. This allows to perform some processing based on metadata, read from the file, before initialising diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt index 1939c209dc34..141fec5d379c 100644 --- a/Documentation/libtracecmd/libtracecmd.txt +++ b/Documentation/libtracecmd/libtracecmd.txt @@ -16,6 +16,8 @@ Open and close trace file: struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_); struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_); void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); + void *tracecmd_set_private*(struct tracecmd_input pass:[*]_handle_, void pass:[*]_data_); + void pass:[*]*tracecmd_get_private*(struct tracecmd_input pass:[*]_handle_); Read tracing records from a trace file: int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);