lttng: Add documentation and TODO files
authorMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Mon, 28 Nov 2011 12:42:22 +0000 (07:42 -0500)
committerGreg Kroah-Hartman <gregkh@suse.de>
Tue, 29 Nov 2011 01:05:07 +0000 (10:05 +0900)
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
drivers/staging/lttng/LICENSE [new file with mode: 0644]
drivers/staging/lttng/README [new file with mode: 0644]
drivers/staging/lttng/TODO [new file with mode: 0644]

diff --git a/drivers/staging/lttng/LICENSE b/drivers/staging/lttng/LICENSE
new file mode 100644 (file)
index 0000000..bb880bf
--- /dev/null
@@ -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 (file)
index 0000000..a154d6e
--- /dev/null
@@ -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 (file)
index 0000000..3fdc5e6
--- /dev/null
@@ -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>