[lttng-dev] [PATCH 15/20] lttng: Add documentation and TODO files

[mathieu.desnoyers@efficios.com (Mathieu Desnoyers)]

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
---
 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 at 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 at 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 at 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 at kroah.com>
+To: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
-- 
1.7.2.5