From: Philippe Proulx Date: Tue, 16 Sep 2014 23:12:28 +0000 (-0400) Subject: Modernize README using Markdown X-Git-Tag: v2.6.0-rc1~55 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=ac2440f2cbbcb03a8f945f7b4c6943f91aeab46d;p=lttng-modules.git Modernize README using Markdown Signed-off-by: Philippe Proulx Signed-off-by: Mathieu Desnoyers --- diff --git a/README b/README deleted file mode 100644 index 119bfa89..00000000 --- a/README +++ /dev/null @@ -1,95 +0,0 @@ -LTTng 2.x modules - -Mathieu Desnoyers -March 29, 2013 - -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, 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). - All the extra information fields to be collected with events are - optional, specified on a per-tracing-session basis (except for - timestamp and event id, which are mandatory). - -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 -# 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 -# depmod -a kernel_version - -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 - -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. - - -* 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 ... -CONFIG_KALLSYMS_ALL: - State dump of mapping between block device number and name. - - -* 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. diff --git a/README.md b/README.md new file mode 100644 index 00000000..f87b47bc --- /dev/null +++ b/README.md @@ -0,0 +1,113 @@ +LTTng-modules +============= + +_by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_ + + +LTTng kernel modules are Linux kernel modules which make +[LTTng](http://lttng.org/) kernel tracing possible. They include +essential control modules and many probes which instrument numerous +interesting parts of Linux. LTTng-modules builds against a vanilla or +distribution kernel, with no need for additional patches. + +Other notable features: + + - Produces [CTF](http://www.efficios.com/ctf) + (Common Trace Format) natively. + - Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU) + counters, kprobes, and kretprobes support. + - Have the ability to attach _context_ information to events in the + trace (e.g., any PMU counter, PID, PPID, TID, command name, etc). + All the extra information fields to be collected with events are + optional, specified on a per-tracing-session basis (except for + timestamp and event ID, which are mandatory). + + +Building +-------- + +To build and install LTTng-modules, you will need to have your kernel +headers available (or access to your full kernel source tree), and do: + + make + sudo make modules_install + sudo depmod -a + +The above commands will build LTTng-modules against your +current kernel. If you need to build LTTng-modules against a custom +kernel, do: + + make KERNELDIR=/path/to/custom/kernel + sudo make KERNELDIR=/path/to/custom/kernel modules_install + sudo depmod -a kernel_version + + +### Required kernel config options + +Make sure your target kernel has the following config options enabled: + + - `CONFIG_MODULES`: loadable module support + - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is + necessary until the few required missing symbols are exported to GPL + modules from mainline + - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source + - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation + (enabled as a side-effect of any of the perf/ftrace/blktrace + instrumentation features) + + +### Supported (optional) kernel config options + +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 probes: + + lttng enable-event -k --probe ... + + - `CONFIG_KRETPROBES`: dynamic function entry/return probes: + + lttng enable-event -k --function ... + + - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device + number and name + + +Using +----- + +Use [LTTng-tools](https://lttng.org/download) to control the tracer. +The session daemon of LTTng-tools should automatically load the LTTng +kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace) +to print traces as a human-readable text log. + + +Support +------- + +So far, it has been tested on various vanilla Linux kernels from 2.6.38 +to 3.16, most of them on IA-32/x86-64 and some of them on ARM and Power-PC +32-bit. Linux 2.6.32 to 2.6.34 need up to 3 patches applied (refer to +[`linux-patches`](linux-patches)). It should work fine with newer kernels and +other architectures, but expect build issues with kernels older than 2.6.36. + + +Notes +----- + +### 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.