From 18b2248a0dcc70284d68ecd095cd2e8451714966 Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Mon, 28 Nov 2011 07:42:22 -0500 Subject: [PATCH] lttng: Add documentation and TODO files Signed-off-by: Mathieu Desnoyers Signed-off-by: Greg Kroah-Hartman --- drivers/staging/lttng/LICENSE | 27 +++++++ drivers/staging/lttng/README | 48 ++++++++++++ drivers/staging/lttng/TODO | 137 ++++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+) create mode 100644 drivers/staging/lttng/LICENSE create mode 100644 drivers/staging/lttng/README create mode 100644 drivers/staging/lttng/TODO diff --git a/drivers/staging/lttng/LICENSE b/drivers/staging/lttng/LICENSE new file mode 100644 index 000000000000..bb880bf1faac --- /dev/null +++ b/drivers/staging/lttng/LICENSE @@ -0,0 +1,27 @@ +LTTng modules licensing +Mathieu Desnoyers +June 2, 2011 + +* LGPLv2.1/GPLv2 dual-license + +The files contained within this package are licensed under +LGPLv2.1/GPLv2 dual-license (see lgpl-2.1.txt and gpl-2.0.txt for +details), except for files identified by the following sections. + +* GPLv2 license + +These files are licensed exclusively under the GPLv2 license. See +gpl-2.0.txt for details. + +lib/ringbuffer/ring_buffer_splice.c +lib/ringbuffer/ring_buffer_mmap.c +instrumentation/events/mainline/*.h +instrumentation/events/lttng-modules/*.h + +* MIT-style license + +These files are licensed under an MIT-style license: + +lib/prio_heap/lttng_prio_heap.h +lib/prio_heap/lttng_prio_heap.c +lib/bitfield.h diff --git a/drivers/staging/lttng/README b/drivers/staging/lttng/README new file mode 100644 index 000000000000..a154d6e19e97 --- /dev/null +++ b/drivers/staging/lttng/README @@ -0,0 +1,48 @@ +LTTng 2.0 modules + +Mathieu Desnoyers +November 1st, 2011 + +LTTng 2.0 kernel modules is currently part of the Linux kernel staging +tree. It features (new features since LTTng 0.x): + +- 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 need to select "Staging" modules, and the +LTTng kernel tracer. + +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 + +Please note that the LTTng-UST 2.0 (user-space tracing counterpart of +LTTng 2.0) is now ready to be used, but still only available from the +git repository. + +So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39 and +3.0 (on x86 32/64-bit, and powerpc 32-bit at the moment, build tested on +ARM). 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 lttng-modules +2.0 can build on a Linux kernel patched with the LTTng 0.x patchset, but +the lttng-modules 2.0 replace the lttng-modules 0.x, so both tracers +cannot be installed at the same time for a given kernel version. + +* 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/drivers/staging/lttng/TODO b/drivers/staging/lttng/TODO new file mode 100644 index 000000000000..3fdc5e684ac2 --- /dev/null +++ b/drivers/staging/lttng/TODO @@ -0,0 +1,137 @@ +Please contact Mathieu Desnoyers for +questions about this TODO list. The "Cleanup/Testing" section would be +good to go through before integration into mainline. The "Features" +section is a wish list of features to complete before releasing the +"LTTng 2.0" final version, but are not required to have LTTng working. +These features are mostly performance enhancements and instrumentation +enhancements. + +TODO: + +A) Cleanup/Testing + + 1) Remove debugfs "lttng" file (keep only procfs "lttng" file). + The rationale for this is that this file is needed for + user-level tracing support (LTTng-UST 2.0) intended to be + used on production system, and therefore should be present as + part of a "usually mounted" filesystem rather than a debug + filesystem. + + 2) Cleanup wrappers. The drivers/staging/lttng/wrapper directory + contains various wrapper headers that use kallsyms lookups to + work around some missing EXPORT_SYMBOL_GPL() in the mainline + kernel. Ideally, those few symbols should become exported to + modules by the kernel. + + 3) Test lib ring buffer snapshot feature. + When working on the lttngtop project, Julien Desfossez + reported that he needed to push the consumer position + forward explicitely with lib_ring_buffer_put_next_subbuf. + This means that although the usual case of pairs of + lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf + work fine, there is probably a problem that needs to be + investigated in + lib_ring_buffer_get_subbuf/lib_ring_buffer_put_subbuf, which + depend on the producer to push the reader position. + Contact: Julien Desfossez + + 4) Test latest -rt kernel support. + There has been report of corrupted traces when tracing a + 3.0.10-rt27 in the area of access_ok() system call event. + Still has to be investigated. Cannot be reproduced with + mainline kernel. + Contact: Yannick Brosseau + +B) Features + + 1) Integration of the LTTng 0.x trace clocks into + LTTng 2.0. + Currently using mainline kernel monotonic clock. NMIs can + therefore not be traced, and this causes a significant + performance degradation compared to the LTTng 0.x trace + clocks. Imply the creation of drivers/staging/lttng/arch to + contain the arch-specific clock support files. + * Dependency: addition of clock descriptions to CTF. + See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary + for the LTTng 0.x git tree. + + 2) Port OMAP3 LTTng trace clocks to x86 to support systems + without constant TSC. + * Dependency: (B.1) + See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary + for the LTTng 0.x git tree. + + 3) Implement mmap operation on an anonymous file created by a + LTTNG_KERNEL_CLOCK ioctl to export data to export + synchronized kernel and user-level LTTng trace clocks: + with: + - shared per-cpu data, + - read seqlock. + The content exported by this shared memory area will be + arch-specific. + * Dependency: (B.1) && (B.2) + See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary + for the LTTng 0.x git tree, which has vDSO support for + LTTng trace clock on the x86 architecture. + + 3) Integrate the "statedump" module from LTTng 0.x into LTTng + 2.0. + * Dependency: addition of "dynamic enumerations" type to CTF. + See: http://git.lttng.org/?p=lttng-modules.git;a=shortlog;h=refs/heads/v0.19-stable + ltt-statedump.c + + 4) Generate system call TRACE_EVENT headers for all + architectures (currently done: x86 32/64). + + 5) Define "unknown" system calls into instrumentation/syscalls + override files / or do SYSCALL_DEFINE improvements to + mainline kernel to allow automatic generation of these + missing system call descriptions. + + 6) Create missing tracepoint event headers files into + instrumentation/events from headers located in + include/trace/events/. Choice: either do as currently done, + and copy those headers locally into the lttng driver and + perform the modifications locally, or push TRACE_EVENT API + modification into mainline headers, which would require + collaboration from Ftrace/Perf maintainers. + + 7) Poll: implement a poll and/or epoll exclusive wakeup scheme, + which contradicts POSIX, but protect multiple consumer + threads from thundering herd effect. + + 8) Re-integrate sample modules from libringbuffer into + lttng driver. Those modules can be used as example of how to + use libringbuffer in other contexts than LTTng, and are + useful to perform benchmarks of the ringbuffer library. + See: http://www.efficios.com/ringbuffer + + 9) NOHZ support for lib ring buffer. NOHZ infrastructure in the + Linux kernel does not support notifiers chains, which does + not let LTTng play nicely with low power consumption setups + for flight recorder (overwrite mode) live traces. One way to + allow integration between NOHZ and LTTng would be to add + support for such notifiers into NOHZ kernel infrastructure. + + 10) Turn drivers/staging/lttng/ltt-probes.c probe_list into a + hash table. Turns O(n^2) trace systems registration (cost + for n systems) into O(n). (O(1) per system) + + 11) drivers/staging/lttng/probes/lttng-ftrace.c: + LTTng currently uses kretprobes for per-function tracing, + not the function tracer. So lttng-ftrace.c should be used + for "all" function tracing. + + 12) drivers/staging/lttng/probes/lttng-types.c: + This is a currently unused placeholder to export entire C + type declarations into the trace metadata, e.g. for support + of describing the layout of structures/enumeration mapping + along with syscall entry events. The design of this support + will likely change though, and become integrated with the + TRACE_EVENT support within lttng, by adding new macros, and + support for generation of metadata from these macros, to + allow description of those compound types/enumerations. + +Please send patches +To: Greg Kroah-Hartman +To: Mathieu Desnoyers -- 2.30.2