Hi Sameer!
On Thu, 25 Mar 2021 22:01:30 +0530
Sameeruddin shaik <sameeruddin.shaik8@xxxxxxxxx> wrote:
> Added documentation for the below API:
> tracefs_function_filter()
>
> Signed-off-by: Sameeruddin shaik <sameeruddin.shaik8@xxxxxxxxx>
>
> 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@xxxxxxxxxxx>
> +*Tzvetomir Stoyanov* <tz.stoyanov@xxxxxxxxx>
> +*sameeruddin shaik* <sameeruddin.shaik8@xxxxxxxxx>
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx>
> +
> +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).
|