[lttng-dev] [PATCH 15/20] lttng: Add documentation and TODO files
Mathieu Desnoyers
mathieu.desnoyers at efficios.com
Mon Nov 28 07:42:22 EST 2011
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
More information about the lttng-dev
mailing list