| From 18b2248a0dcc70284d68ecd095cd2e8451714966 Mon Sep 17 00:00:00 2001 |
| From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> |
| Date: Mon, 28 Nov 2011 07:42:22 -0500 |
| Subject: lttng: Add documentation and TODO files |
| |
| Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> |
| Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de> |
| --- |
| drivers/staging/lttng/LICENSE | 27 ++++++++ |
| drivers/staging/lttng/README | 48 ++++++++++++++ |
| drivers/staging/lttng/TODO | 137 +++++++++++++++++++++++++++++++++++++++++ |
| 3 files changed, 212 insertions(+), 0 deletions(-) |
| 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 0000000..bb880bf |
| --- /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 0000000..a154d6e |
| --- /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 0000000..3fdc5e6 |
| --- /dev/null |
| +++ b/drivers/staging/lttng/TODO |
| @@ -0,0 +1,137 @@ |
| +Please contact Mathieu Desnoyers <mathieu.desnoyers@efficios.com> 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 <julien.desfossez@polymtl.ca> |
| + |
| + 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 <yannick.brosseau@polymtl.ca> |
| + |
| +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 <greg@kroah.com> |
| +To: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> |
| -- |
| 1.7.9 |
| |