[PATCH 0/9] libtraceevent: Add checks for man pages

[PATCH 0/9] libtraceevent: Add checks for man pages

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add the check code from libtracefs that makes sure every function in
event-parse.h is documented in man pages, and that every man page entry is
listed in the top level libtraceevent man page.

Steven Rostedt (Google) (9):
  libtraceevent: Add check-manpages.sh
  libtraceevent: Update man page to reflect tep_is_pid_registered()
    rename
  libtraceevent: Add printk documentation to libtraceevent man page
  libtraceevent: Add tep_get_function_count() to libtraceevent man page
  libtraceevent: Include meta data functions in libtraceevent man pages
  libtraceevent: Add some missing functions to generic libtraceevent man
    page
  libtraceevent: Add man page for tep_plugin_add_option()
  libtraceevent: Add man page documentation of tep_get_sub_buffer_size()
  libtraceevent: Add tep_print_field() to check-manpages.sh deprecated

 Documentation/libtraceevent-commands.txt  |  2 +-
 Documentation/libtraceevent-page_size.txt | 10 ++++-
 Documentation/libtraceevent-plugins.txt   |  9 +++-
 Documentation/libtraceevent.txt           | 22 +++++++++
 Makefile                                  |  5 ++-
 check-manpages.sh                         | 54 +++++++++++++++++++++++
 6 files changed, 98 insertions(+), 4 deletions(-)
 create mode 100755 check-manpages.sh

-- 
2.35.1

[PATCH 1/9] libtraceevent: Add check-manpages.sh

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

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
"libtraceevent" as well as making sure that all functions in
event-parse.h is also documented.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 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 a32052385e9e..dcd4ad9689ff 100644
--- a/Makefile
+++ b/Makefile
@@ -378,7 +378,7 @@ uninstall: $(BUILD_OUTPUT)/build_uninstall
 	@$(foreach file,$(shell cat $(BUILD_OUTPUT)/build_uninstall),$(call uninstall_file,$(file)))
 
 PHONY += doc
-doc:
+doc: check_doc
 	$(Q)$(call descend,$(src)/Documentation,)
 
 PHONY += doc-clean
@@ -389,6 +389,9 @@ PHONY += doc-install
 doc-install:
 	$(Q)$(call descend,$(src)/Documentation,install)
 
+check_doc: force
+	$(Q)$(src)/check-manpages.sh $(src)/Documentation
+
 
 PHONY += doc-uninstall
 doc-uninstall:
diff --git a/check-manpages.sh b/check-manpages.sh
new file mode 100755
index 000000000000..a2f4f264b42b
--- /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 <rostedt@goodmis.org>
+#
+# 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=libtraceevent
+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/traceevent/event-parse.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 event-parse.h"
+			last=$f
+		fi
+		echo "   ${f}"
+	fi
+done
-- 
2.35.1

[PATCH 2/9] libtraceevent: Update man page to reflect tep_is_pid_registered() rename

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The commit that renamed tep_pid_is_registered to
tep_is_pid_registered() missed a location that had the old name.

Fixes: 241ac93c8527 ("tools tools, tools lib traceevent: Make traceevent APIs more consistent")
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent-commands.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/libtraceevent-commands.txt b/Documentation/libtraceevent-commands.txt
index 185ff16a1352..cea3001df888 100644
--- a/Documentation/libtraceevent-commands.txt
+++ b/Documentation/libtraceevent-commands.txt
@@ -3,7 +3,7 @@ libtraceevent(3)
 
 NAME
 ----
-tep_register_comm, tep_override_comm, tep_pid_is_registered,
+tep_register_comm, tep_override_comm, tep_is_pid_registered,
 tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid -
 Manage pid to process name mappings.
 
-- 
2.35.1

[PATCH 3/9] libtraceevent: Add printk documentation to libtraceevent man page

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add the parsing of trace_printk() to the generic documentation page.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 6476070737f5..4fe8939788a5 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -39,6 +39,12 @@ Register / unregister APIs:
 	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_);
 
+Trace printk parsing:
+	void *tep_print_printk*(struct tep_handle pass:[*]tep);
+	void *tep_print_funcs*(struct tep_handle pass:[*]tep);
+	void *tep_set_test_filters*(struct tep_handle pass:[*]tep, int test_filters);
+	void *tep_plugin_print_options*(struct trace_seq pass:[*]s);
+
 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_);
-- 
2.35.1

[PATCH 4/9] libtraceevent: Add tep_get_function_count() to libtraceevent man page

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add tep_get_function_count() to the generic libtraceevent man page.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 4fe8939788a5..06abaf7a6b74 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -38,6 +38,7 @@ Register / unregister APIs:
 	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_);
+	int *tep_get_function_count*(struct tep_handle *_tep_);
 
 Trace printk parsing:
 	void *tep_print_printk*(struct tep_handle pass:[*]tep);
-- 
2.35.1

[PATCH 5/9] libtraceevent: Include meta data functions in libtraceevent man pages

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add the functions to parse the metadata printk_formats, kallsyms and
saved_cmdlines to the generic libtraceevent man page.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 06abaf7a6b74..77b50362cdb8 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -46,6 +46,11 @@ Trace printk parsing:
 	void *tep_set_test_filters*(struct tep_handle pass:[*]tep, int test_filters);
 	void *tep_plugin_print_options*(struct trace_seq pass:[*]s);
 
+Meta data parsing:
+	int *tep_parse_saved_cmdlines*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
+	int *tep_parse_printk_formats*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
+	int *tep_parse_kallsyms*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
+
 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_);
-- 
2.35.1

[PATCH 6/9] libtraceevent: Add some missing functions to generic libtraceevent man page

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

Add tep_load_plugins_hook() and tep_add_plugin_path() to the generic
libtraceevent man page.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 77b50362cdb8..6f342a8162d7 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -59,6 +59,14 @@ Plugins management:
 	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_);
+	void *tep_load_plugins_hook*(struct tep_handle pass:[*]_tep_, const char pass:[*]_suffix_,
+			   void (pass:[*]_load_plugin_)(struct tep_handle pass:[*]tep,
+					       const char pass:[*]path,
+					       const char pass:[*]name,
+					       void pass:[*]data),
+			   void pass:[*]_data_);
+	int *tep_add_plugin_path*(struct tep_handle pass:[*]tep, char pass:[*]path,
+			  enum tep_plugin_load_priority prio);
 
 Event related APIs:
 	struct tep_event pass:[*]*tep_get_event*(struct tep_handle pass:[*]_tep_, int _index_);
-- 
2.35.1

[PATCH 7/9] libtraceevent: Add man page for tep_plugin_add_option()

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The man page for tep_plugin_add_option() was missing, so add it.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent-plugins.txt | 9 ++++++++-
 Documentation/libtraceevent.txt         | 1 +
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/libtraceevent-plugins.txt b/Documentation/libtraceevent-plugins.txt
index 24d8ad84ef5c..4ca78d453d73 100644
--- a/Documentation/libtraceevent-plugins.txt
+++ b/Documentation/libtraceevent-plugins.txt
@@ -3,7 +3,8 @@ libtraceevent(3)
 
 NAME
 ----
-tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook, tep_add_plugin_path - Load / unload traceevent plugins.
+tep_load_plugins, tep_unload_plugins, tep_load_plugins_hook, tep_add_plugin_path,
+tep_plugin_add_option - Load / unload traceevent plugins.
 
 SYNOPSIS
 --------
@@ -21,6 +22,7 @@ void *tep_load_plugins_hook*(struct tep_handle pass:[*]_tep_, const char pass:[*
 			   void pass:[*]_data_);
 int *tep_add_plugin_path*(struct tep_handle pass:[*]tep, char pass:[*]path,
 			  enum tep_plugin_load_priority prio);
+int *tep_plugin_add_option*(const char pass:[*]_name_, const char pass:[*]_val_);
 --
 
 DESCRIPTION
@@ -76,6 +78,11 @@ plugin wins. The priority can be:
 Where the plugins in TEP_PLUGIN_LAST" will take precedence over the
 plugins in the other directories.
 
+The *tep_plugin_add_option()* sets options defined by a plugin. The _name_ is the
+name of the option to set to _val_. Plugins can add options to change its behavior
+and *tep_plugin_add_option()* is used by the application to make those modifications.
+
+
 RETURN VALUE
 ------------
 The *tep_load_plugins()* function returns a list of successfully loaded plugins,
diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 6f342a8162d7..045437cb2282 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -45,6 +45,7 @@ Trace printk parsing:
 	void *tep_print_funcs*(struct tep_handle pass:[*]tep);
 	void *tep_set_test_filters*(struct tep_handle pass:[*]tep, int test_filters);
 	void *tep_plugin_print_options*(struct trace_seq pass:[*]s);
+	int *tep_plugin_add_option*(const char pass:[*]_name_, const char pass:[*]_val_);
 
 Meta data parsing:
 	int *tep_parse_saved_cmdlines*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
-- 
2.35.1

[PATCH 8/9] libtraceevent: Add man page documentation of tep_get_sub_buffer_size()

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

The man page for tep_get_sub_buffer_size() is missing, add it.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 Documentation/libtraceevent-page_size.txt | 10 +++++++++-
 Documentation/libtraceevent.txt           |  1 +
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/libtraceevent-page_size.txt b/Documentation/libtraceevent-page_size.txt
index 7ffeb790002a..6d0dd36e3d68 100644
--- a/Documentation/libtraceevent-page_size.txt
+++ b/Documentation/libtraceevent-page_size.txt
@@ -3,7 +3,7 @@ libtraceevent(3)
 
 NAME
 ----
-tep_get_page_size, tep_set_page_size - Get / set the size of a memory page on
+tep_get_page_size, tep_set_page_size, tep_get_sub_buffer_size - Get / set the size of a memory page on
 the machine, where the trace is generated
 
 SYNOPSIS
@@ -14,6 +14,7 @@ SYNOPSIS
 
 int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
 void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
+int *tep_get_sub_buffer_size*(struct tep_handle pass:[*]_tep_);
 --
 
 DESCRIPTION
@@ -27,10 +28,17 @@ 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.
 
+The *tep_get_sub_buffer_size()* returns the size of each "sub buffer" of the
+ring buffer. The Linux kernel ring buffer is broken up into sections called
+sub buffers. This returns the size of those buffers.
+
 RETURN VALUE
 ------------
 The *tep_get_page_size()* function returns size of the memory page, in bytes.
 
+The *tep_get_sub_buffer_size()* function returns the number of bytes each sub
+buffer is made up of.
+
 EXAMPLE
 -------
 [source,c]
diff --git a/Documentation/libtraceevent.txt b/Documentation/libtraceevent.txt
index 045437cb2282..0d0795e79b53 100644
--- a/Documentation/libtraceevent.txt
+++ b/Documentation/libtraceevent.txt
@@ -26,6 +26,7 @@ Management of tep handler data structure and access of its members:
 	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_);
+	int *tep_get_sub_buffer_size*(struct tep_handle pass:[*]_tep_);
 	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_);
-- 
2.35.1

[PATCH 9/9] libtraceevent: Add tep_print_field() to check-manpages.sh deprecated

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

As tep_print_field() is deprecated, do not report it as missing from the
man pages.

Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
 check-manpages.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/check-manpages.sh b/check-manpages.sh
index a2f4f264b42b..06a94f154ff9 100755
--- a/check-manpages.sh
+++ b/check-manpages.sh
@@ -37,7 +37,7 @@ for man in ${MAIN}-*.txt; do
 	done
 done
 
-DEPRECATED=""
+DEPRECATED="*tep_print_field*"
 
 sed -ne 's/^[a-z].*[ \*]\([a-z_][a-z_]*\)(.*/\1/p' -e 's/^\([a-z_][a-z_]*\)(.*/\1/p' ../include/traceevent/event-parse.h | while read f; do
 	if ! grep -q '\*'${f}'\*' $MAIN_FILE; then
-- 
2.35.1