Re: [PATCH] libtracefs: Document function_filter API

[Steven Rostedt <rostedt@goodmis.org>]

Hi Sameer!

On Thu, 25 Mar 2021 22:01:30 +0530
Sameeruddin shaik <sameeruddin.shaik8@gmail.com> wrote:

> Added documentation for the below API:
> tracefs_function_filter()
> 
> Signed-off-by: Sameeruddin shaik <sameeruddin.shaik8@gmail.com>
> 
> diff --git a/Documentation/libtracefs-function-filter.txt b/Documentation/libtracefs-function-filter.txt
> new file mode 100644
> index 0000000..08eece7
> --- /dev/null
> +++ b/Documentation/libtracefs-function-filter.txt
> @@ -0,0 +1,116 @@
> +libtracefs(3)
> +=============
> +
> +NAME
> +----
> +tracefs_function_filter -  Function to write to set_ftrace_filter
> +file of specific instance or top tracing instance

Since we are abstracting out tracefs, I'd like to avoid the implementation
details, and keep it more about its functionality.

 - Function to limit kernel functions that are traced

> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <tracefs.h>*
> +
> +int tracefs_function_filter(struct tracefs_instance *instance, const char **filters, const char *module, bool reset, const char ***errs);
> +--
> +
> +DESCRIPTION
> +-----------
> +This Function can be used to write to set_ftrace_file in the trace
> +filesystem, which will limit the trace to only those functions,
> +which were written in the file.

To avoid stating the implementation:

"This function can be used to limit the Linux kernel functions that is
traced by the function and function-graph tracers."


> +
> +It will take take _instance_argument, that can be NULL for the
> +top level tracing, _filters_, which is nothing but the array of the

No need to say "nothing"

"which is an array of strings that represent a list of filters that should
be applied to define what functions are to be traced. The array must end
with a NULL pointer."

> +strings to write into the set_ftrace_filter file ,_module_ , name of the
> +module to be traced, _reset_, to reset or append the filters to file

"_reset_ if set will clear the current set of filters and then apply the
filter list, otherwise the list of filters are added to the current set of
filters."

> + and _errs_ which is again an array of failed filters, which can be NULL

"and _errs_ is a pointer an array of strings, which will be allocated if
any of filters fail to any available function. If _errs_ is NULL, it will
be ignored."

> + if failed filters are not of concern, and  returns 0  on successful write,
> + 1 or -x (where x is an integer) on error.

I mentioned in a previous email that I think we need to change the return
value, but for now this is fine.

> +
> +RETURN VALUE
> +------------
> +tracefs_function_filter will return 0 on successful write to file, if there

Just need to say ".. return 0 on success."

> +is error, it will return 1 for general errors or negative number -x(x denotes
> +number of failed filters), if there are any failed filters.

Again, I think the error return may be changed, so we can leave this for
now.

> +
> +In case of negative return value, errs have to be checked and must be freed
> +using the free()
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <tracefs.h>
> +
> +#define INST "dummy"
> +
> +const char *filters[] = { "run_init_process", "try_to_run_init_process", "dummy1", NULL };
> +
> +int main(int argc, char *argv[])
> +{
> +	struct tracefs_instance *inst = tracefs_instance_create(INST);
> +	const char **errs = NULL;
> +	bool reset = 1;
> +	int ret;
> +	int i = 0;
> +
> +	if (!inst) {
> +	   /* Error creating new trace instance*/
> +	   }
> +
> +	ret = tracefs_function_filter(inst, filters, NULL, reset, &errs);
> +
> +	if (ret < 0 && errs) {
> +	   	while (errs[i])
> +		      printf("%s\n", errs[i++]);
> +	      }
> +
> +	tracefs_instance_free(inst);
> +	tracefs_instance_destroy(inst);
> +	free(errs);
> +	return 0;

This looks fine.

Thanks!

-- Steve

> +}
> +--
> +
> +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>
> +*sameeruddin shaik* <sameeruddin.shaik8@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).