X-Git-Url: http://git.liburcu.org/?p=lttng-modules.git;a=blobdiff_plain;f=README.md;h=66bf925394dfe099c9ee185bb8664ee742f25996;hp=f87b47bc468a24bb1ea758cff97bdb03c5b2a5c5;hb=HEAD;hpb=ac2440f2cbbcb03a8f945f7b4c6943f91aeab46d diff --git a/README.md b/README.md index f87b47bc..d1e4dbb6 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ distribution kernel, with no need for additional patches. Other notable features: - Produces [CTF](http://www.efficios.com/ctf) - (Common Trace Format) natively. + (Common Trace Format) natively, - Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU) - counters, kprobes, and kretprobes support. + 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 @@ -42,18 +42,31 @@ kernel, do: sudo depmod -a kernel_version +### Kernel built-in support + +It is also possible to build these modules as part of a kernel image. Simply +run the [`scripts/built-in.sh`](scripts/built-in.sh) script with the path to +your kernel source directory as an argument. It will symlink the +lttng-modules directory in the kernel sources and add an include in the kernel +Makefile. + +Then configure your kernel as usual and enable the `CONFIG_LTTNG` option. + + ### Required kernel config options Make sure your target kernel has the following config options enabled: - - `CONFIG_MODULES`: loadable module support + - `CONFIG_MODULES`: loadable module support (not strictly required + when built into the kernel), - `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 + 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) + instrumentation features). + - `CONFIG_KPROBES` (5.7+): use kallsyms for kernel 5.7 and newer. ### Supported (optional) kernel config options @@ -82,8 +95,36 @@ available from LTTng: - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device number and name +### LTTng specific kernel config options + +The following kernel configuration options are provided by LTTng: + + - `CONFIG_LTTNG`: Build LTTng (Defaults to 'm'). + - `CONFIG_LTTNG_EXPERIMENTAL_BITWISE_ENUM`: Enable the experimental bitwise + enumerations (Defaults to 'n'). This can be enabled by building with: + + make CONFIG_LTTNG_EXPERIMENTAL_BITWISE_ENUM=y -Using + - `CONFIG_LTTNG_CLOCK_PLUGIN_TEST`: Build the test clock plugin (Defaults to + 'm'). This plugin overrides the trace clock and should always be built as a + module for testing. + + +Customization/Extension +----------------------- + +The lttng-modules source includes definitions for the actual callback +functions that will be attached to the kernel tracepoints by lttng. +The lttng-modules project implements its own macros generating these +callbacks: the LTTNG_TRACEPOINT_EVENT macro family found in +instrumentation/events/lttng-module/. In order to show up in a +lttng-modules trace, a kernel tracepoint must be defined within the +kernel tree, and also defined within lttng-modules with the +LTTNG_TRACEPOINT_EVENT macro family. Customizations or extensions must +be done by modifying instances of these macros within the lttng-modules +source. + +Usage ----- Use [LTTng-tools](https://lttng.org/download) to control the tracer. @@ -95,11 +136,7 @@ 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. +Linux kernels >= 4.4 are supported. Notes @@ -111,3 +148,45 @@ 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. + + +Supported versions +------------------ + +The LTTng project supports the last two released stable versions +(e.g. stable-2.13 and stable-2.12). + +Fixes are backported from the master branch to the last stable version +unless those fixes would break the ABI or API. Those fixes may be backported +to the second-last stable version, depending on complexity and ABI/API +compatibility. + +Security fixes are backported from the master branch to both of the last stable +version and the the second-last stable version. + +New kernel version enablement commits are integrated into the master branch and +backported to the last stable version. + +New features are integrated into the master branch and not backported to the +last stable branch. + +Contacts +-------- + +You can contact the maintainers on the following mailing list: +`lttng-dev@lists.lttng.org`. + +IRC channel: [#lttng](irc://irc.oftc.net/lttng) on the OFTC network + +Bug tracker: [LTTng-modules bug tracker](https://bugs.lttng.org/projects/lttng-modules) + +Code review: [_lttng-modules_ project](https://review.lttng.org/q/project:lttng-modules) on LTTng Review + +Continuous integration: [LTTng-modules](https://ci.lttng.org/view/LTTng-modules/) on LTTng's CI + +GitHub mirror: [lttng/lttng-modules](https://github.com/lttng/lttng-modules) + +Patches are principally submitted and reviewed on [LTTng Review](https://review.lttng.org), +but may also be submitted to the [mailing list](mailto:lttng-dev@lists.lttng.org) +with the subject prefix `PATCH lttng-modules` or by pull request on the +[GitHub mirror](https://github.com/lttng/lttng-modules).