[PATCH 0/2] libtracefs: Update option documentation and return pointer

[PATCH 0/2] libtracefs: Update option documentation and return pointer

[Steven Rostedt]

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

This is on top of this series:
  https://lore.kernel.org/linux-trace-devel/20210408140024.13093-1-y.karadz@gmail.com/

Have the trace_options_get_*() functions return a constant pointer as
the bitmask returned points to an internal structure, and should not be
freed or modified by the caller.

Fix the option documentation about how options are related between the
top instance and the created instance.

Move the tracefs_option_mask_is_set() documentation to the other
tarce_option_*() man page and remove the old documentation file.

Steven Rostedt (VMware) (2):
  libtracefs: Have the option mask function return a const pointer
  libtracefs: Document tracefs_option_mask_is_set() with the other
    option functions

 Documentation/libtracefs-option-bits.txt | 90 ------------------------
 Documentation/libtracefs-option-get.txt  | 29 +++++---
 include/tracefs.h                        |  4 +-
 src/tracefs-tools.c                      | 10 +--
 4 files changed, 29 insertions(+), 104 deletions(-)
 delete mode 100644 Documentation/libtracefs-option-bits.txt

-- 
2.29.2

[PATCH 1/2] libtracefs: Have the option mask function return a const pointer

[Steven Rostedt]

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

As the pointer returned by the tracefs_options_get_*() point to the
instance field, it must not be freed or modified by the caller. Have the
return value of the mask be a constant, and update the documentation to
reflect this.

Also fixed the documentation about supported options. If an option is
supported in the top level instance, it may *not* be supported in a
created instance. Currently all options supported in the created instance
are also supported at the top level, but there's no guarantee that will be
the case in the future. All created instances (mkdir in instances
directory) have the same supported options.

Link: https://lore.kernel.org/linux-trace-devel/CAPpZLN7G4AttMVFhwtf_YVouRtXhtNyHBK7QqEZWzAEeGhU_9Q@mail.gmail.com/

Suggested-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
---
 Documentation/libtracefs-option-get.txt | 16 +++++++++-------
 include/tracefs.h                       |  4 ++--
 src/tracefs-tools.c                     | 10 ++++++----
 3 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/Documentation/libtracefs-option-get.txt b/Documentation/libtracefs-option-get.txt
index 3290f24..f1c3502 100644
--- a/Documentation/libtracefs-option-get.txt
+++ b/Documentation/libtracefs-option-get.txt
@@ -12,9 +12,9 @@ SYNOPSIS
 --
 *#include <tracefs.h>*
 
-struct tracefs_options_mask pass:[*]*tracefs_options_get_supported*(struct tracefs_instance pass:[*]_instance_);
+const struct tracefs_options_mask pass:[*]*tracefs_options_get_supported*(struct tracefs_instance pass:[*]_instance_);
 bool *tracefs_option_is_supported*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
-struct tracefs_options_mask pass:[*]*tracefs_options_get_enabled*(struct tracefs_instance pass:[*]_instance_);
+const struct tracefs_options_mask pass:[*]*tracefs_options_get_enabled*(struct tracefs_instance pass:[*]_instance_);
 bool *tracefs_option_is_enabled*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
 --
 
@@ -25,11 +25,12 @@ depend on the kernel version and the kernel configuration.
 
 The _tracefs_options_get_supported()_ function gets all ftrace options supported by the system in
 the given _instance_. If _instance_ is NULL, supported options of the top trace instance are
-returned. The set of supported options must be the same in all trace instances.
+returned. The set of supported options is the same in all created trace instances, but may be different
+than the top trace instance.
 
 The _tracefs_option_is_supported()_ function checks if the option with given _id_ is supported by
 the system in the given _instance_. If _instance_ is NULL, the top trace instance is used. If an
-option is supported at the top trace instance, it must be supported in all trace instances also.
+option is supported at the top trace instance, it it may not be supported in a created trace instance.
 
 The _tracefs_options_get_enabled()_ function gets all ftrace options, currently enabled in
 the given _instance_. If _instance_ is NULL, enabled options of the top trace instance are returned.
@@ -39,9 +40,10 @@ given _instance_. If _instance_ is NULL, the top trace instance is used.
 
 RETURN VALUE
 ------------
-The _tracefs_options_get_supported()_ and _tracefs_options_get_enabled()_ functions return pointer
-to allocated bitmask with trace options, or NULL in case of an error. The returned bitmask must be
-freed with free();
+The _tracefs_options_get_supported()_ and _tracefs_options_get_enabled()_ functions, on success,
+return a pointer to the bitmask within the instance, or a global bitmask for the top level,
+or NULL in case of an error. As the returned bitmask is part of the instance structure (or a
+global variable) and must not be freed or modified.
 
 The _tracefs_option_is_supported()_ and _tracefs_option_is_enabled()_ functions return true if the
 option in supported / enabled, or false otherwise.
diff --git a/include/tracefs.h b/include/tracefs.h
index c761d12..2dc29b3 100644
--- a/include/tracefs.h
+++ b/include/tracefs.h
@@ -145,9 +145,9 @@ enum tracefs_option_id {
 struct tracefs_options_mask;
 bool tracefs_option_mask_is_set(const struct tracefs_options_mask *options,
 				enum tracefs_option_id id);
-struct tracefs_options_mask *tracefs_options_get_supported(struct tracefs_instance *instance);
+const struct tracefs_options_mask *tracefs_options_get_supported(struct tracefs_instance *instance);
 bool tracefs_option_is_supported(struct tracefs_instance *instance, enum tracefs_option_id id);
-struct tracefs_options_mask *tracefs_options_get_enabled(struct tracefs_instance *instance);
+const struct tracefs_options_mask *tracefs_options_get_enabled(struct tracefs_instance *instance);
 bool tracefs_option_is_enabled(struct tracefs_instance *instance, enum tracefs_option_id id);
 int tracefs_option_enable(struct tracefs_instance *instance, enum tracefs_option_id id);
 int tracefs_option_diasble(struct tracefs_instance *instance, enum tracefs_option_id id);
diff --git a/src/tracefs-tools.c b/src/tracefs-tools.c
index bb0110e..1ce8c3d 100644
--- a/src/tracefs-tools.c
+++ b/src/tracefs-tools.c
@@ -208,8 +208,8 @@ enum tracefs_option_id tracefs_option_id(const char *name)
 	return TRACEFS_OPTION_INVALID;
 }
 
-static struct tracefs_options_mask *trace_get_options(struct tracefs_instance *instance,
-						      bool enabled)
+const static struct tracefs_options_mask *
+trace_get_options(struct tracefs_instance *instance, bool enabled)
 {
 	pthread_mutex_t *lock = instance ? &instance->lock : &toplevel_lock;
 	struct tracefs_options_mask *bitmask;
@@ -266,7 +266,8 @@ error:
  * Returns bitmask structure with all trace options, supported in given instance,
  * or NULL in case of an error.
  */
-struct tracefs_options_mask *tracefs_options_get_supported(struct tracefs_instance *instance)
+const struct tracefs_options_mask *
+tracefs_options_get_supported(struct tracefs_instance *instance)
 {
 	return trace_get_options(instance, false);
 }
@@ -278,7 +279,8 @@ struct tracefs_options_mask *tracefs_options_get_supported(struct tracefs_instan
  * Returns bitmask structure with all trace options, enabled in given instance,
  * or NULL in case of an error.
  */
-struct tracefs_options_mask *tracefs_options_get_enabled(struct tracefs_instance *instance)
+const struct tracefs_options_mask *
+tracefs_options_get_enabled(struct tracefs_instance *instance)
 {
 	return trace_get_options(instance, true);
 }
-- 
2.29.2

[PATCH 2/2] libtracefs: Document tracefs_option_mask_is_set() with the other option functions

[Steven Rostedt]

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

As tracefs_option_is_set() was renamed to tracefs_option_mask_is_set() and
is tightly coupled with the tracefs_option_get_*() functions, remove its
man page and document it along with the other tracefs_option_*()
functions.

Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
---
 Documentation/libtracefs-option-bits.txt | 90 ------------------------
 Documentation/libtracefs-option-get.txt  | 13 +++-
 2 files changed, 12 insertions(+), 91 deletions(-)
 delete mode 100644 Documentation/libtracefs-option-bits.txt

diff --git a/Documentation/libtracefs-option-bits.txt b/Documentation/libtracefs-option-bits.txt
deleted file mode 100644
index d713a5e..0000000
--- a/Documentation/libtracefs-option-bits.txt
+++ /dev/null
@@ -1,90 +0,0 @@
-libtracefs(3)
-=============
-
-NAME
-----
-tracefs_option_set, tracefs_option_clear, tracefs_option_is_set -
-Set, clear, check option in a bitmask.
-
-SYNOPSIS
---------
-[verse]
---
-*#include <tracefs.h>*
-
-void *tracefs_option_set*(struct tracefs_options_mask pass:[*]_options_, enum tracefs_option_id _id_);
-void *tracefs_option_clear*(struct tracefs_options_mask pass:[*]_options_, enum tracefs_option_id _id_);
-bool *tracefs_option_is_set*(struct tracefs_options_mask _options_, enum tracefs_option_id _id_);
---
-
-DESCRIPTION
------------
-This set of APIs can be used to manipulate a bitmask with option IDs.
-
-The _tracefs_option_set()_ function sets the bit, corresponding to the option with _id_ in the
-_options_ bitmask.
-
-The _tracefs_option_clear()_ function clears the bit, corresponding to the option with _id_ in the
-_options_ bitmask.
-
-The _tracefs_option_is_set()_ function checks if the bit, corresponding to the option with _id_ is
-set in the _options_ bitmask.
-
-RETURN VALUE
-------------
-The _tracefs_option_is_set()_ function returns true if the bit is set, false otherwise.
-
-EXAMPLE
--------
-[source,c]
---
-#include <tracefs.h>
-...
-struct tracefs_options_mask options;
-memset(&options, 0, sizeof(options));
-...
-tracefs_option_set(&options, TRACEFS_OPTION_EVENT_FORK | TRACEFS_OPTION_FUNCTION_FORK);
-...
-if (tracefs_option_is_set(options, TRACEFS_OPTION_EVENT_FORK))
-	tracefs_option_clear(&options, TRACEFS_OPTION_EVENT_FORK);
-...
---
-FILES
------
-[verse]
---
-*tracefs.h*
-	Header file to include in order to have access to the library APIs.
-*-ltracefs*
-	Linker switch to add when building a program that uses the library.
---
-
-SEE ALSO
---------
-_libtracefs(3)_,
-_libtraceevent(3)_,
-_trace-cmd(1)_
-
-AUTHOR
-------
-[verse]
---
-*Steven Rostedt* <rostedt@goodmis.org>
-*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
---
-REPORTING BUGS
---------------
-Report bugs to  <linux-trace-devel@vger.kernel.org>
-
-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) 2020 VMware, Inc. Free use of this software is granted under
-the terms of the GNU Public License (GPL).
diff --git a/Documentation/libtracefs-option-get.txt b/Documentation/libtracefs-option-get.txt
index f1c3502..ea5e21b 100644
--- a/Documentation/libtracefs-option-get.txt
+++ b/Documentation/libtracefs-option-get.txt
@@ -4,7 +4,8 @@ libtracefs(3)
 NAME
 ----
 tracefs_options_get_supported, tracefs_option_is_supported,
-tracefs_options_get_enabled, tracefs_option_is_enabled - Get and check ftrace options.
+tracefs_options_get_enabled, tracefs_option_is_enabled, tracefs_option_mask_is_set
+- Get and check ftrace options.
 
 SYNOPSIS
 --------
@@ -16,6 +17,7 @@ const struct tracefs_options_mask pass:[*]*tracefs_options_get_supported*(struct
 bool *tracefs_option_is_supported*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
 const struct tracefs_options_mask pass:[*]*tracefs_options_get_enabled*(struct tracefs_instance pass:[*]_instance_);
 bool *tracefs_option_is_enabled*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_);
+bool *tracefs_option_mask_is_set*(const struct tracefs_options_mask *options, enum tracefs_option_id id);
 --
 
 DESCRIPTION
@@ -38,6 +40,9 @@ the given _instance_. If _instance_ is NULL, enabled options of the top trace in
 The _tracefs_option_is_enabled()_ function checks if the option with given _id_ is enabled in the
 given _instance_. If _instance_ is NULL, the top trace instance is used.
 
+The _tracefs_option_mask_is_set()_ function checks if the bit, corresponding to the option with _id_ is
+set in the _options_ bitmask returned from _tracefs_option_get_enabled()_ and _tracefs_option_is_supported()_.
+
 RETURN VALUE
 ------------
 The _tracefs_options_get_supported()_ and _tracefs_options_get_enabled()_ functions, on success,
@@ -48,6 +53,9 @@ global variable) and must not be freed or modified.
 The _tracefs_option_is_supported()_ and _tracefs_option_is_enabled()_ functions return true if the
 option in supported / enabled, or false otherwise.
 
+The _tracefs_option_mask_is_set()_ returns true if the corresponding option is set in the mask
+or false otherwise.
+
 EXAMPLE
 -------
 [source,c]
@@ -69,6 +77,9 @@ if (!options) {
 } else {
 	...
 }
+if (tracefs_options_mask_is_set(options, TRACEFS_OPTION_LATENCY_FORMAT)) {
+	...
+}
 ...
 
 if (tracefs_option_is_supported(NULL, TRACEFS_OPTION_LATENCY_FORMAT)) {
-- 
2.29.2