From 151469222a6e322caaf245152c9f0246a0f377af Mon Sep 17 00:00:00 2001 From: compudj Date: Mon, 6 Mar 2006 18:03:33 +0000 Subject: [PATCH] add readme git-svn-id: http://ltt.polymtl.ca/svn@1585 04897980-b3bd-0310-b5e0-8ef037075253 --- usertrace-generic/Makefile | 16 +- usertrace-generic/README | 164 ++++++++++++++++++ .../ltt-facility-loader-user_generic.c | 4 + usertrace-generic/sample-printf.c | 3 +- 4 files changed, 180 insertions(+), 7 deletions(-) create mode 100644 usertrace-generic/README diff --git a/usertrace-generic/Makefile b/usertrace-generic/Makefile index 91e09a85..f3e52e1a 100644 --- a/usertrace-generic/Makefile +++ b/usertrace-generic/Makefile @@ -1,22 +1,26 @@ - CC=gcc +INCLUDE_DIR=/usr/include all: sample-thread sample sample-highspeed sample-printf sample-thread: sample-thread.c ltt-facility-loader-user_generic.c - $(CC) $(CFLAGS) -I. -lpthread -o $@ $^ + $(CC) $(CFLAGS) -lpthread -o $@ $^ sample: sample.c ltt-facility-loader-user_generic.c - $(CC) $(CFLAGS) -I. -o $@ $^ + $(CC) $(CFLAGS) -o $@ $^ sample-highspeed: sample-highspeed.c ltt-facility-loader-user_generic.c - $(CC) $(CFLAGS) -I. -o $@ $^ + $(CC) $(CFLAGS) -o $@ $^ sample-printf: sample-printf.c ltt-facility-loader-user_generic.c - $(CC) $(CFLAGS) -I. -o $@ $^ + $(CC) $(CFLAGS) -o $@ $^ + +.PHONY : clean install -.PHONY : clean +install: + if [ ! -e "$(INCLUDE_DIR)/ltt" ] ; then mkdir $(INCLUDE_DIR)/ltt ; fi + cp -f ltt/*.h $(INCLUDE_DIR)/ltt clean: rm -fr *.o *~ sample-thread sample sample-highspeed sample-printf diff --git a/usertrace-generic/README b/usertrace-generic/README new file mode 100644 index 00000000..f466cf47 --- /dev/null +++ b/usertrace-generic/README @@ -0,0 +1,164 @@ + +LTTng usertrace generic package + +Mathieu Desnoyers +March 2006 + +This package contains all the user space headers and c files necessary to make +your application and library trace through an active LTTng tracer. Here is a +short quickstart guide of it. + +Here are the currently supported architectures : +x86 +(please add the ltt_* system calls to other architectures as you need them : it +will work magically) + +* Compile your kernel with the latest LTTng patch. Make sure the option + "Allow tracing from userspace" is _active_! + See the QUICKSTART guide at http://ltt.polymtl.ca/ for details about how to + setup a working tracer and viewer. See the genevent installation step : it is + required for method #2 below. + +* Extract the latest usertrace-generic archive : +su +cd /usr/src +wget http://ltt.polymtl.ca/packages/usertrace-generic-x.x.tar.gz +gzip -cd usertrace-generic-x.x.tar.gz | tar xvof - + +* Build the sample programs and install the headers into your system : +su +cd /usr/src/usertrace-generic +make +make install + +* There are two ways to trace information from your application : + +1) Easy way, but slow (printf style) + See sample-printf.c for code example. + +- Add the following statements to your program source (the define must come + _before_ the includes!) : + +#define LTT_TRACE +#define LTT_BLOCKING 1 +#include +#include + +Note the define of LTT_BLOCKING to 1 : if a trace buffer is full, your +application will block. The default of this parameter is 0 (non blocking) : +events are lost when trace buffer is full. The choice is up to you. + +- Add something like the following sample line in your code. Note that this is a + very standard format string, this is only a suggested presentation. + +trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.", + __FILE__, __func__, __LINE__, count); + +- Compile your application with at least these parameters to gcc (it is splitted + on two lines, joined by a "\") : +gcc -D LTT_SHOW_DEBUG -I /usr/src/usertrace-generic -o myapp myapp.c \ + /usr/src/usertrace-generic/ltt-facility-loader-user_generic.c + +To see what the final result looks like : +- Start tracing +- Start your application + ** You should see the following message when your program starts and the + LTT_SHOW_DEBUG is defined : + "LTT : ltt-facility-user_generic init in userspace" + If you don't then you forgot to compile the facility loader in your + application. If you find this output annoying, you can remove the + "-D LTT_SHOW_DEBUG" gcc parameter, which will make the facility loader + silent. +- Stop tracing +Then, to see only the user_generic events : +lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic" + +It will show : +user_generic.slow_printf: 35885.922829472 (/cpu_0), 15521, 7453, SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 0." } +user_generic.slow_printf: 35886.925685289 (/cpu_0), 15521, 7453, SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 1." } +... + + + +2) The second way to log events is still easy, yet faster. It requires creating + your own XML description of your data structures. It will make it easier to + identify your data in the trace. Please read the comments in method 1) + explained previously, as they are not repeated here. + See sample.c for code example. + +- Go to the usertrace-generic directory +su +cd /usr/src/usertrace-generic + +- Create your own facility (i.e. user_myfacility.xml). + See the ones available in /usr/share/LinuxTraceToolkitViewer/facilities for + examples. + You facility _must_ be named following this standard : "user_*", where * is + whatever you like. If it is not, it will be rejected by the kernel with a + Operation not permitted (can be seen with the -D LTT_SHOW_DEBUG compilation + parameter). + +user_myfacility.xml: + + + Sample facility + + Sample event + + + + + + + + +- AN IMPORTANT STEP FOLLOWS : + *copy* the user_myfacility.xml file in your system : +su +cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities + +- Use genevent to create the c code and headers : +su +cd /tmp +mkdir genevent +cd genevent +for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml; + do /usr/local/bin/genevent $a; +done +cd /usr/src/usertrace-generic +cp /tmp/genevent/*load* . +cd ltt +cp /tmp/genevent/ltt-facility-id-user_myfacility.h . +cp /tmp/genevent/ltt-facility-user_myfacility.h . +cd .. +make install + +- Add the following statements to your program source (the define must come + _before_ the includes!) : + +#define LTT_TRACE +#define LTT_BLOCKING 1 +#include + +- Add a call following the trace_user_myfacility_myevent function found in + /usr/include/ltt/ltt-facility-user_myfacility.h in your program. +For instance : +trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0); + +- Compile your application with at least these parameters to gcc (it is splitted + on two lines, joined by a "\") : +gcc -I /usr/src/usertrace-generic -o myapp myapp.c \ + /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c + +To see what the final result looks like : +- Start tracing +- Start your application +- Stop tracing +Then, to see only the user_myfacility events : +lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility" + +It will show, for example : +user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736, SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 } + + + diff --git a/usertrace-generic/ltt-facility-loader-user_generic.c b/usertrace-generic/ltt-facility-loader-user_generic.c index 292f407c..8cdb0760 100644 --- a/usertrace-generic/ltt-facility-loader-user_generic.c +++ b/usertrace-generic/ltt-facility-loader-user_generic.c @@ -33,13 +33,17 @@ static struct user_facility_info facility = { static void __attribute__((constructor)) __ltt_user_init(void) { int err; +#ifdef LTT_SHOW_DEBUG printf("LTT : ltt-facility-user_generic init in userspace\n"); +#endif //LTT_SHOW_DEBUG err = ltt_register_generic(<T_FACILITY_SYMBOL, &facility); LTT_FACILITY_CHECKSUM_SYMBOL = LTT_FACILITY_SYMBOL; if(err) { +#ifdef LTT_SHOW_DEBUG perror("Error in ltt_register_generic"); +#endif //LTT_SHOW_DEBUG } } diff --git a/usertrace-generic/sample-printf.c b/usertrace-generic/sample-printf.c index 980b653f..85fd6507 100644 --- a/usertrace-generic/sample-printf.c +++ b/usertrace-generic/sample-printf.c @@ -14,7 +14,8 @@ int main(int argc, char **argv) unsigned int count = 0; while(1) { - trace_user_generic_slow_printf("Counter value is : %u.", count); + trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.", + __FILE__, __func__, __LINE__, count); count++; sleep(1); } -- 2.34.1