| Message ID | 20190308133654.21264-16-tstoyanov@vmware.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Libtraceevent MAN pages | expand |
On Fri, 8 Mar 2019 15:36:23 +0200 Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote: > Create man pages for tep_register_function() and tep_register_print_string() > as part of the libtraceevent APIs. > > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com> > --- > .../libtraceevent-reg_funcstr.txt | 89 +++++++++++++++++++ > 1 file changed, 89 insertions(+) > create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt > > diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt > new file mode 100644 > index 000000000000..fdb9e0352586 > --- /dev/null > +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt > @@ -0,0 +1,89 @@ > +libtraceevent(3) > +================ > + > +NAME > +---- > +tep_register_function, tep_register_print_string - Registers a function / string > +with a given address. > + > +SYNOPSIS > +-------- > +[verse] > +-- > +*#include <event-parse.h>* > + > +int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); > +int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); > +-- > + > +DESCRIPTION > +----------- > +The _tep_register_function()_ function registers a function name with an > +address and module. The _tep_ argument is the trace event parser context. The > +_name_ is the name of the function, the string is copied internally. The _addr_ > +is the start address of the function. The _mod_ is the kernel module > +the function may be in (NULL for none). I would elaborate here more about what this means. What is registered is kernel function name that is mapped to an address that will be used in function look ups. For the function tracer or events that have a "%pF" or "%pS" in the format string. It is common to pass in the kallsyms function names with their corresponding addresses with this function. > + > +The _tep_register_print_string()_ function registers a string by the address > +it was stored in the kernel. The _tep_ argument is the trace event parser > +context. The _fmt_ is the string to register, it is copied internally. The _addr_ > +is the address the string was located at. Some strings internal to the kernel with static address are passed to certain events. The "%s" in the format field which has an address will need to know what string would be at that address. The tep_register_print_string() supplies the parsing with the mapping between kernel addresses and those strings. -- Steve > + > +RETURN VALUE > +------------ > +The _tep_register_function()_ function returns 0 in case of success. In case of > +an error -1 is returned, and errno is set to the appropriate error number. > + > +The _tep_register_print_string()_ function returns 0 in case of success. In case > +of an error -1 is returned, and errno is set to the appropriate error number. > + > +EXAMPLE > +------- > +[source,c] > +-- > +#include <event-parse.h> > +... > +struct tep_handle *tep = tep_alloc(); > +... > + if (tep_register_function(tep, "my_custom_func", > + (unsigned long long) 0x12345678, NULL) != 0) { > + /* Failed to register my_custom_func address mapping */ > + } > +... > + if (tep_register_print_string(tep, "print string", > + (unsigned long long) 0x87654321, NULL) != 0) { > + /* Failed to register "print string" address mapping */ > + } > +-- > +FILES > +----- > +[verse] > +-- > +*event-parse.h* > + Header file to include in order to have access to the library APIs. > +*-ltraceevent* > + Linker switch to add when building a program that uses the library. > +-- > + > +SEE ALSO > +-------- > +_libtraceevent(3)_, _trace-cmd(1)_ > + > +AUTHOR > +------ > +[verse] > +-- > +*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. > +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. > +-- > +REPORTING BUGS > +-------------- > +Report bugs to <linux-trace-devel@vger.kernel.org> > + > +LICENSE > +------- > +libtraceevent is Free Software licensed under the GNU LGPL 2.1 > + > +RESOURCES > +--------- > +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
On Fri, 8 Mar 2019 15:36:23 +0200 Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote: > +EXAMPLE > +------- > +[source,c] > +-- > +#include <event-parse.h> > +... > +struct tep_handle *tep = tep_alloc(); > +... > + if (tep_register_function(tep, "my_custom_func", > + (unsigned long long) 0x12345678, NULL) != 0) { There's a whitespace bug in the above string. Also, I wouldn't use "my_custom_func" as the example name, as its not for custom names. I would use "kernel_function_X" or something similar. -- Steve > + /* Failed to register my_custom_func address mapping */ > + } > +... > + if (tep_register_print_string(tep, "print string", > + (unsigned long long) 0x87654321, NULL) != 0) { > + /* Failed to register "print string" address mapping */ > + } > +--
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt new file mode 100644 index 000000000000..fdb9e0352586 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt @@ -0,0 +1,89 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_function, tep_register_print_string - Registers a function / string +with a given address. + +SYNOPSIS +-------- +[verse] +-- +*#include <event-parse.h>* + +int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); +int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); +-- + +DESCRIPTION +----------- +The _tep_register_function()_ function registers a function name with an +address and module. The _tep_ argument is the trace event parser context. The +_name_ is the name of the function, the string is copied internally. The _addr_ +is the start address of the function. The _mod_ is the kernel module +the function may be in (NULL for none). + +The _tep_register_print_string()_ function registers a string by the address +it was stored in the kernel. The _tep_ argument is the trace event parser +context. The _fmt_ is the string to register, it is copied internally. The _addr_ +is the address the string was located at. + +RETURN VALUE +------------ +The _tep_register_function()_ function returns 0 in case of success. In case of +an error -1 is returned, and errno is set to the appropriate error number. + +The _tep_register_print_string()_ function returns 0 in case of success. In case +of an error -1 is returned, and errno is set to the appropriate error number. + +EXAMPLE +------- +[source,c] +-- +#include <event-parse.h> +... +struct tep_handle *tep = tep_alloc(); +... + if (tep_register_function(tep, "my_custom_func", + (unsigned long long) 0x12345678, NULL) != 0) { + /* Failed to register my_custom_func address mapping */ + } +... + if (tep_register_print_string(tep, "print string", + (unsigned long long) 0x87654321, NULL) != 0) { + /* Failed to register "print string" address mapping */ + } +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Create man pages for tep_register_function() and tep_register_print_string() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com> --- .../libtraceevent-reg_funcstr.txt | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt