Message ID | 1616689890-18853-1-git-send-email-sameeruddin.shaik8@gmail.com (mailing list archive) |
---|---|
State | Superseded |
Headers | show |
Series | libtracefs: Document function_filter API | expand |
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).
hi steve, On 25/03/21 3:10 am, Steven Rostedt wrote: > 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. In future, when the changes were made, i will change this man page accordingly. >> + >> +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).
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 + +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. + +It will take take _instance_argument, that can be NULL for the +top level tracing, _filters_, which is nothing but the array of the +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 + and _errs_ which is again an array of failed filters, which can be NULL + if failed filters are not of concern, and returns 0 on successful write, + 1 or -x (where x is an integer) on error. + +RETURN VALUE +------------ +tracefs_function_filter will return 0 on successful write to file, if there +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. + +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; +} +-- + +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).
Added documentation for the below API: tracefs_function_filter() Signed-off-by: Sameeruddin shaik <sameeruddin.shaik8@gmail.com>