Update the README file to mark the project as unmaintained

[lttv.git] / LTTngManual.html

diff --git a/LTTngManual.html b/LTTngManual.html
index 58c49470a4bbfe3a3770a08a9e4c9c88d084a807..10978001793975f4867738ff5f0bf34a4bcfa3dd 100644 (file)
--- a/LTTngManual.html
+++ b/LTTngManual.html
@@ -8,7 +8,7 @@
 <h1>Linux Trace Toolkit Next Generation Manual</h1>
 
 Author : Mathieu Desnoyers, September 2005<br>
 <h1>Linux Trace Toolkit Next Generation Manual</h1>
 
 Author : Mathieu Desnoyers, September 2005<br>

-Last update : January 21st, 2009<br>
+Last update : September 3, 2010<br>

 (originally known as the LTTng QUICKSTART guide)
 
 <h2>Table of Contents</h2>
 (originally known as the LTTng QUICKSTART guide)
 
 <h2>Table of Contents</h2>


@@ -16,6 +16,8 @@ Last update : January 21st, 2009<br>
 <ul>
 <li><a href="#intro" name="TOCintro">Introduction</a></li>
 <ul>
 <ul>
 <li><a href="#intro" name="TOCintro">Introduction</a></li>
 <ul>

+<li><a href="#licenses" name="TOClicenses">Licenses</a></li>
+<ul>

 <li><a href="#arch" name="TOCarch">Supported architectures</a></li>
 </ul>
 
 <li><a href="#arch" name="TOCarch">Supported architectures</a></li>
 </ul>
 


@@ -74,10 +76,10 @@ packages from the LTTng and LTTV sources.
 These operations are made for installing the LTTng 0.86 tracer on a linux 2.6.X
 kernel. You will also find instructions for installation of LTTV 0.12.x : the
 Linux Trace Toolkit Viewer. 
 These operations are made for installing the LTTng 0.86 tracer on a linux 2.6.X
 kernel. You will also find instructions for installation of LTTV 0.12.x : the
 Linux Trace Toolkit Viewer. 

-To see the list of compatibilities between LTTng, ltt-control, LTTV, please
-refer to :
+To see the list of compatibilities between the LTTng kernel patchset, LTTng
+modules, ltt-control, LTTV, please refer to :

 <a
 <a

-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV versions compatibility</a>
+href="http://lttng.org/cgi-bin/gitweb.cgi?p=lttv.git;a=blob_plain;f=doc/developer/lttng-lttv-compatibility.html;hb=HEAD">LTTng+LTTV versions compatibility</a>

 
 The ongoing work had the Linux Kernel Markers integrated in the mainline Linux
 kernel since Linux 2.6.24 and the Tracepoints since 2.6.28. In its current
 
 The ongoing work had the Linux Kernel Markers integrated in the mainline Linux
 kernel since Linux 2.6.24 and the Tracepoints since 2.6.28. In its current


@@ -87,8 +89,26 @@ kernel.
 
 <br>
 <br>
 
 <br>
 <br>

+<h3><a href="#TOClicenses" name="licenses">Licenses</a></h3>
+<p>
+LTTng, UST and LTTV are developed by an open community. LTTng is released under
+a dual Gnu LGPLv2.1/GPLv2 license, except for very few kernel-specific files
+which are derived work from the Linux kernel.
+<p>
+LTTV is available under the Gnu GPLv2. The low-level LTTV trace reading library
+is released under Gnu LGPLv2.1.
+<p>
+The Eclipse LTTng trace analysis tool is released under the EPL and uses the
+LTTV trace reading library (LGPLv2.1).
+<p>
+The UST (Userspace Tracing) and the Userspace RCU libraries are released under
+the LGPLv2.1 license, which allows linking with non-GPL (BSD, proprietary...)
+applications. The associated headers are released under MIT-style/BSD-style
+licenses.
+<p>
+Please refer to each particular file licensing for details.
+

 <h3><a href="#TOCarch" name="arch">Supported architectures</a></h3>
 <h3><a href="#TOCarch" name="arch">Supported architectures</a></h3>

-<br>

 LTTng :<br>
 <br>
 <li> x86 32/64 bits
 LTTng :<br>
 <br>
 <li> x86 32/64 bits


@@ -154,7 +174,7 @@ gtk 2.4 or better development libraries
   (Fedora : gtk2, gtk2-devel)
   note : For Fedora users : this might require at least core 3 from Fedora,
   or you might have to compile your own GTK2 library.
   (Fedora : gtk2, gtk2-devel)
   note : For Fedora users : this might require at least core 3 from Fedora,
   or you might have to compile your own GTK2 library.

-glib 2.4 or better development libraries
+glib 2.16 or better development libraries

   (Debian : libglib2.0-0, libglib2.0-dev)
   (Fedora : glib2, glib2-devel)
 libpopt development libraries
   (Debian : libglib2.0-0, libglib2.0-dev)
   (Fedora : glib2, glib2-devel)
 libpopt development libraries


@@ -174,8 +194,7 @@ libc6 development librairies
 <p>
 See the list of compatibilities between LTTng, ltt-control and LTTV at :
 <a
 <p>
 See the list of compatibilities between LTTng, ltt-control and LTTV at :
 <a

-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV
-versions compatibility</a>.
+href="http://lttng.org/cgi-bin/gitweb.cgi?p=lttv.git;a=blob_plain;f=doc/developer/lttng-lttv-compatibility.html;hb=HEAD">LTTng+LTTV versions compatibility</a>.

 
 
 <h3><a href="#TOCgetlttng" name="getlttng">Getting the LTTng packages</a></h3>
 
 
 <h3><a href="#TOCgetlttng" name="getlttng">Getting the LTTng packages</a></h3>


@@ -184,9 +203,11 @@ versions compatibility</a>.
 su -
 mkdir /usr/src/lttng
 cd /usr/src/lttng
 su -
 mkdir /usr/src/lttng
 cd /usr/src/lttng

-(see http://ltt.polymtl.ca/lttng for package listing)
-wget http://ltt.polymtl.ca/lttng/patch-2.6.X-lttng-0.x.xx.tar.bz2
+(see http://lttng.org/files/lttng for package listing)
+wget http://lttng.org/files/lttng/patch-2.6.X-lttng-0.x.xx.tar.bz2
+wget http://lttng.org/files/lttng/lttng-modules-0.x.tar.bz2

 bzip2 -cd patch-2.6.X-lttng-0.x.xx.tar.bz2 | tar xvof -
 bzip2 -cd patch-2.6.X-lttng-0.x.xx.tar.bz2 | tar xvof -

+bzip2 -cd lttng-modules-0.x.tar.bz2 | tar xvof -

 </PRE>
 
 
 </PRE>
 
 


@@ -212,7 +233,7 @@ mv linux-2.6.X linux-2.6.X-lttng-0.x.xx
 su -
 cd /usr/src/linux-2.6.X-lttng-0.x.xx
 make menuconfig (or make xconfig or make config)
 su -
 cd /usr/src/linux-2.6.X-lttng-0.x.xx
 make menuconfig (or make xconfig or make config)

-    Select the < Help > button if you are not familiar with kernel
+    Select the &lt; Help &gt; button if you are not familiar with kernel

     configuration.
     Items preceded by [*] means they has to be built into the kernel.
     Items preceded by [M] means they has to be built as modules.
     configuration.
     Items preceded by [*] means they has to be built into the kernel.
     Items preceded by [M] means they has to be built as modules.


@@ -221,23 +242,10 @@ make menuconfig (or make xconfig or make config)
     Select the following options :
     [*] Prompt for development and/or incomplete code/drivers
     [*] Activate markers
     Select the following options :
     [*] Prompt for development and/or incomplete code/drivers
     [*] Activate markers

-    [*] Activate userspace markers ABI (experimental, optional)

     [*] Immediate value optimization (optional)
     [*] Immediate value optimization (optional)

-    [*] Linux Trace Toolkit Next Generation (LTTng) --->
-    <M> or <*> Compile lttng tracing probes
-    <M> or <*> Linux Trace Toolkit High-speed Lockless Data Relay
-    <M> or <*> Linux Trace Toolkit Lock-Protected Data Relay
-    <M> or <*> Linux Trace Toolkit Serializer
-    <M> or <*>   Linux Trace Toolkit Marker Control
-    <M> or <*>     Linux Trace Toolkit Tracer
-    [*] Align Linux Trace Toolkit Traces
-    <M> or <*> Support logging events from userspace
-    [*] Support trace extraction from crash dump
-    <M> or <*> Linux Trace Toolkit Trace Controller
-    <M> or <*> Linux Trace Toolkit State Dump
-  Select <Exit>
-  Select <Exit>
-  Select <Yes>
+  Select &lt;Exit&gt;
+  Select &lt;Exit&gt;
+  Select &lt;Yes&gt;

 make
 make modules_install
 (if necessary, create a initrd with mkinitrd or your preferate alternative)
 make
 make modules_install
 (if necessary, create a initrd with mkinitrd or your preferate alternative)


@@ -263,6 +271,22 @@ Select the Linux 2.6.X-lttng-0.x.xx kernel in your boot loader.
 --
 </PRE>
 
 --
 </PRE>
 

+
+<h3><a href="#TOCinstalllttng" name="installlttng">Installing the LTTng modules</a></h3>
+
+<PRE>
+su -
+cd /usr/src/lttng/lttng-modules-0.x
+KERNELDIR=/usr/src/linux-2.6.X-lttng-0.x.xx make
+KERNELDIR=/usr/src/linux-2.6.X-lttng-0.x.xx make modules_install
+
+Optionally, make can be prefixed with tracer options:
+
+EXTRA_CFLAGS="-DLTT_DEBUG_EVENT_SIZE" make
+EXTRA_CFLAGS="-DLTT_VMCORE" make
+EXTRA_CFLAGS="-DLTT_DEBUG_EVENT_SIZE -DLTT_VMCORE" make
+</PRE>
+

 <h3><a href="#TOCeditconfig" name="editconfig">Editing the system wide
 configuration</a></h3>
 
 <h3><a href="#TOCeditconfig" name="editconfig">Editing the system wide
 configuration</a></h3>
 


@@ -293,7 +317,6 @@ compile statically, you may not need to issue all these commands.
 modprobe ltt-trace-control
 modprobe ltt-marker-control
 modprobe ltt-tracer
 modprobe ltt-trace-control
 modprobe ltt-marker-control
 modprobe ltt-tracer

-modprobe ltt-serialize

 modprobe ltt-relay
 modprobe ipc-trace
 modprobe kernel-trace
 modprobe ltt-relay
 modprobe ipc-trace
 modprobe kernel-trace


@@ -304,6 +327,7 @@ modprobe jbd2-trace
 modprobe ext4-trace
 modprobe syscall-trace
 modprobe trap-trace
 modprobe ext4-trace
 modprobe syscall-trace
 modprobe trap-trace

+modprobe block-trace

 #if locking tracing is wanted, uncomment the following
 #modprobe lockdep-trace
 </PRE>
 #if locking tracing is wanted, uncomment the following
 #modprobe lockdep-trace
 </PRE>


@@ -324,7 +348,6 @@ cp /etc/modules /etc/modules.bkp
 echo ltt-trace-control >> /etc/modules
 echo ltt-marker-control >> /etc/modules
 echo ltt-tracer >> /etc/modules
 echo ltt-trace-control >> /etc/modules
 echo ltt-marker-control >> /etc/modules
 echo ltt-tracer >> /etc/modules

-echo ltt-serialize >> /etc/modules

 echo ltt-relay >> /etc/modules
 echo ipc-trace >> /etc/modules
 echo kernel-trace >> /etc/modules
 echo ltt-relay >> /etc/modules
 echo ipc-trace >> /etc/modules
 echo kernel-trace >> /etc/modules


@@ -349,7 +372,7 @@ same name as the ltt-control kernel module, they are *not* the same thing.)
 <PRE>
 su -
 cd /usr/src
 <PRE>
 su -
 cd /usr/src

-wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz
+wget http://lttng.org/files/lttng/ltt-control-0.x-xxxx2006.tar.gz

 gzip -cd ltt-control-0.x-xxxx2008.tar.gz | tar xvof -
 cd ltt-control-0.x-xxxx2006
 (refer to README to see the development libraries that must be installed on you
 gzip -cd ltt-control-0.x-xxxx2008.tar.gz | tar xvof -
 cd ltt-control-0.x-xxxx2006
 (refer to README to see the development libraries that must be installed on you


@@ -365,12 +388,12 @@ ldconfig
 
 <PRE>
 Make sure you selected the kernel menuconfig option :
 
 <PRE>
 Make sure you selected the kernel menuconfig option :

-    <M> or <*> Support logging events from userspace
+    &lt;M&gt; or &lt;*&gt; Support logging events from userspace

 And that the ltt-userspace-event kernel module is loaded if selected as a
 module.
 
 Simple userspace tracing is available through
 And that the ltt-userspace-event kernel module is loaded if selected as a
 module.
 
 Simple userspace tracing is available through

-echo "some text to record" > /mnt/debugfs/ltt/write_event
+echo "some text to record" &gt; /mnt/debugfs/ltt/write_event

 
 It will appear in the trace under event :
 channel : userspace
 
 It will appear in the trace under event :
 channel : userspace


@@ -384,7 +407,7 @@ or different from the visualisation machine)</a></h3>
 <PRE>
 su -
 cd /usr/src
 <PRE>
 su -
 cd /usr/src

-wget http://ltt.polymtl.ca/packages/lttv-0.x.xx-xxxx2008.tar.gz
+wget http://lttng.org/files/packages/lttv-0.x.xx-xxxx2008.tar.gz

 gzip -cd lttv-0.x.xx-xxxx2008.tar.gz | tar xvof -
 cd lttv-0.x.xx-xxxx2008
 (refer to README to see the development libraries that must be installed on your
 gzip -cd lttv-0.x.xx-xxxx2008.tar.gz | tar xvof -
 cd lttv-0.x.xx-xxxx2008
 (refer to README to see the development libraries that must be installed on your


@@ -523,18 +546,16 @@ for LTTng probe examples.
 <h3><a href="#TOCusertp" name="usertp">Adding userspace instrumentation</a></h3>
 
 Add new events to userspace programs with
 <h3><a href="#TOCusertp" name="usertp">Adding userspace instrumentation</a></h3>
 
 Add new events to userspace programs with

-<a href="http://ltt.polymtl.ca/packages/">userspace markers packages</a>.
+<a href="http://lttng.org/files/packages/">userspace markers packages</a>.

 Get the latest markers-userspace-*.tar.bz2 and see the Makefile and examples. It
 allows inserting markers in executables and libraries, currently only on x86_32
 and x86_64.
 See <a
 Get the latest markers-userspace-*.tar.bz2 and see the Makefile and examples. It
 allows inserting markers in executables and libraries, currently only on x86_32
 and x86_64.
 See <a

-href="http://ltt.polymtl.ca/packages/markers-userspace-0.5.tar.bz2">markers-userspace-0.5.tar.bz2</a> or more recent.
+href="http://lttng.org/files/packages/markers-userspace-0.5.tar.bz2">markers-userspace-0.5.tar.bz2</a> or more recent.

 
 <p>
 
 <p>

-Note that a new design document for a 3rd generation of tracepoint/marker-based
-userspace tracing is available at <a
-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/ust.html">LTTng User-space Tracing
-Design</a>. This new infrastructure is not yet implemented.
+Note that tracepoint/marker-based userspace tracing is available at <a
+href="http://lttng.org/ust/">LTTng User-space Tracer (UST)</a>.

 
 <p>
 The easy quick-and-dirty way to perform userspace tracing is currently to write
 
 <p>
 The easy quick-and-dirty way to perform userspace tracing is currently to write