X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=README;h=9aa5b93953c1bbfdf361831389eab23d1439a37b;hb=refs%2Fheads%2Fstable-2.4;hp=fb0561df4f798741820f099053b30ce2847ef0c0;hpb=fe17837951dce26cb69450161716d7a621380441;p=lttng-modules.git

diff --git a/README b/README
index fb0561df..9aa5b939 100644
--- a/README
+++ b/README
@@ -1,15 +1,15 @@
-LTTng 2.0 modules
+LTTng 2.x modules
 
 Mathieu Desnoyers
-July 19, 2011
+March 29, 2013
 
-LTTng 2.0 kernel modules build against a vanilla or distribution kernel, without
+LTTng 2.x kernel modules build against a vanilla or distribution kernel, without
 need for additional patches. Other features:
 
 - Produces CTF (Common Trace Format) natively,
   (http://www.efficios.com/ctf)
 - Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
-  counters and kprobes support,
+  counters, kprobes, and kretprobes support,
 - Integrated interface for both kernel and userspace tracing,
 - Have the ability to attach "context" information to events in the
   trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).
@@ -20,27 +20,74 @@ need for additional patches. Other features:
 To build and install, you will need to have your kernel headers available (or
 access to your full kernel source tree), and use:
 
-make
-make modules_install
+% make
+# make modules_install
+# depmod -a
 
 If you need to specify the target directory to the kernel you want to build
 against, use:
 
-KERNELDIR=path_to_kernel_dir make
-KERNELDIR=path_to_kernel_dir make modules_install
+% KERNELDIR=path_to_kernel_dir make
+# KERNELDIR=path_to_kernel_dir make modules_install
+# depmod -a kernel_version
 
-Use lttng-tools (git://git.lttng.org/lttng-tools.git) to control the tracer.
-LTTng tools should automatically load the kernel modules when needed.
+Use lttng-tools to control the tracer. LTTng tools should automatically load
+the kernel modules when needed. Use Babeltrace to print traces as a
+human-readable text log. These tools are available at the following URL:
+http://lttng.org/lttng2.0
 
-Use Babeltrace (git://git.efficios.com/babeltrace.git) to print traces as a
-human-readable text log.
+So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39, 3.0,
+3.1, 3.2, 3.3 (on x86 32/64-bit, and powerpc 32-bit at the moment, build
+tested on ARM), 3.4, 3.5, 3.8, 3.9-rc on x86 64-bit. Kernels 2.6.32 to
+2.6.34 need up to 3 patches applied (refer to linux-patches within the
+lttng-modules tree). It should work fine with newer kernels and other
+architectures, but expect build issues with kernels older than 2.6.36.
+The clock source currently used is the standard gettimeofday (slower,
+less scalable and less precise than the LTTng 0.x clocks).  Support for
+LTTng 0.x clocks will be added back soon into LTTng 2.0.
 
-Please note that the LTTng-UST 2.0 (user-space tracing counterpart of LTTng 2.0)
-is still in active development and not released yet.
 
-So far, it has been tested on vanilla kernels 2.6.38 and 2.6.39 (on x86 at the
-moment). It should work fine with newer kernels and other architectures, but
-expect build issues with kernels older than 2.6.36. The clock source currently
-used is the standard gettimeofday (slower, less scalable and less precise than
-the LTTng 0.x clocks). Support for LTTng 0.x clocks will be added back soon into
-LTTng 2.0.
+* Kernel config options required
+
+CONFIG_MODULES: required
+  * Kernel modules support.
+CONFIG_KALLSYMS: required
+  * See wrapper/ files. This is necessary until the few required missing
+    symbols are exported to GPL modules from mainline.
+CONFIG_HIGH_RES_TIMERS: required
+  * Needed for LTTng 2.0 clock source.
+CONFIG_TRACEPOINTS: required
+    kernel tracepoint instrumentation
+    * Enabled as side-effect of any of the perf/ftrace/blktrace
+      instrumentation features.
+
+
+* Kernel config options supported (optional)
+
+The following kernel configuration options will affect the features
+available from LTTng:
+
+
+CONFIG_HAVE_SYSCALL_TRACEPOINTS:
+            system call tracing
+               lttng enable-event -k --syscall
+               lttng enable-event -k -a
+CONFIG_PERF_EVENTS:
+            performance counters
+               lttng add-context -t perf:*
+CONFIG_EVENT_TRACING:
+            needed to allow block layer tracing
+CONFIG_KPROBES:
+            Dynamic probe.
+               lttng enable-event -k --probe ...
+CONFIG_KRETPROBES:
+            Dynamic function entry/return probe.
+               lttng enable-event -k --function ...
+
+
+* Note about Perf PMU counters support
+
+Each PMU counter has its zero value set when it is attached to a context with
+add-context. Therefore, it is normal that the same counters attached to both the
+stream context and event context show different values for a given event; what
+matters is that they increment at the same rate.