update compat

[lttv.git] / ltt / branches / poly / QUICKSTART

diff --git a/ltt/branches/poly/QUICKSTART b/ltt/branches/poly/QUICKSTART
index d5d5b8f89d66bea1430ddbaeffe17f4f2756d632..8df06a833d403c9a9de5c45c55fd7d0c77323647 100644 (file)
--- a/ltt/branches/poly/QUICKSTART
+++ b/ltt/branches/poly/QUICKSTART
@@ -13,84 +13,263 @@ What you will typically want is to read sections 1 and 3 : install LTTng from
 binary packages and use it. If there are no packages ready for your system, you
 will have to install from sources (section 2) instead.
 
 binary packages and use it. If there are no packages ready for your system, you
 will have to install from sources (section 2) instead.
 

-These operations are made for installing LTTng 0.2 on a linux 2.6.12-rc2-mm2
-kernel. Change the versions to fit your needs.
+These operations are made for installing the LTTng 0.5.0 tracer on a
+linux 2.6.14 kernel. You will also find instructions for installtion of
+LTTV 0.8.x : the Linux Trace Toolkit Viewer.

 
 

-Author : Mathieu Desnoyers, September 2005
+The following lttng patch is necessary to have the tracing hooks in the kernel.
+The following ltt-control module controls the tracing.
+
+Required programs and librairies are assumed to be automatically installed in an
+installation with Debian or RPM packages. In the case of an installation from
+sources, the dependencies are listed.
+
+
+** Current development status **
+
+LTTng : 
+supported architectures : 
+Intel Pentium (UP/SMP) with TSC

 
 

+LTTV :
+supported architectures :
+Intel i386 and better
+Intel 64 bits
+PowerPC
+
+
+
+Author : Mathieu Desnoyers, September 2005
+Last update : December 31, 2005

 
 
 ***********************************************************
 ** Section 1 * Installation from Debian or RPM packages  **
 ***********************************************************
 
 
 
 ***********************************************************
 ** Section 1 * Installation from Debian or RPM packages  **
 ***********************************************************
 

-No Debian or RPM packages are ready yet.
+** NOTE : RPM and debian packages are only made once a version has been
+   thoroughly tested. If they do not exist at the moment, please install from
+        sources (see section 2 below).
+
+
+* Install from RPM packages on Fedora Core 4 :
+
+Get LTTV RPM from :
+
+http://ltt.polymtl.ca/packages/fedora/RPMS
+
+LTTV RPM are ready.
+
+LTTng kernel and lttng-modules RPM are available for some architectures (i586,
+i686). Feel free to help fix the spec files to have correct lttng-modules RPM
+package.
+
+
+* Install from Deb packages on Debian :
+
+You can use the ltt.polymtl.ca apt source to get LTTV for Debian :
+
+Add the following two sources to your /etc/apt/sources.list :
+
+deb http://ltt.polymtl.ca/packages/debian experimental main
+deb-src http://ltt.polymtl.ca/packages/debian experimental main
+
+
+* Install from precompiled binary packages (LTTV compiled only for i386, and
+  LTTng only for i686 smp), perform the following :
+
+su -
+apt-get update
+apt-get install lttv lttv-doc
+apt-get install kernel-image-2.6.12-rc4-mm2-lttng-0.4.2
+apt-get install lttng-modules-modules-2.6.12-rc4-mm2-lttng-0.4.2
+  * note : the packages are signed by myself. I am not considered a trusted
+    Debian source yet, so warnings are normal.
+
+Then, follow the section "Editing the system wide configuration" in section 2.
+
+* Create custom LTTV Debian packages
+
+Binary packages are only available for i386. If you want to create your own LTTV
+packages for other platforms, do :
+
+su -
+cd /usr/src
+apt-get source lttv
+cd lttv-0.6.9
+dpkg-buildpackage -rfakeroot
+
+You should then have your LTTV .deb files created for your architecture.
+
+* Create custom LTTng packages
+
+For building LTTng Debian packages :
+
+su -
+apt-get install kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
+cd /usr/src
+bzip2 -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2.tar.bz2 | tar xvof -
+cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
+make menuconfig (or xconfig or config) (customize your configuration)
+make-kpkg kernel_image
+
+You will then see your freshly created .deb in /usr/src. Install it with
+dpkg -i /usr/src/(image-name).deb
+
+You will also need to create a package for the lttng-modules :
+
+su -
+cd /usr/src
+apt-get source lttng-modules
+cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
+make-kpkg --added_modules /usr/src/lttng-modules-0.3 modules_image
+
+You will then see your freshly created .deb in /usr/src. Install it with
+dpkg -i /usr/src/lttng-modules-modules-(your version).deb

 
 

-TODO
+
+Then, follow the section "Editing the system wide configuration" in section 2.

 
 
 ***********************************************************
 ** Section 2 * Installation from sources                 **
 ***********************************************************
 
 
 
 ***********************************************************
 ** Section 2 * Installation from sources                 **
 ***********************************************************
 

+* Prerequisites
+
+Tools needed to follow the package download steps :
+
+o wget
+o bzip2
+o gzip
+o tar
+
+You have to install the standard development librairies and programs necessary
+to compile a kernel :
+
+(from Documentation/Changes in the Linux kernel tree)
+o  Gnu C                  2.95.3                  # gcc --version
+o  Gnu make               3.79.1                  # make --version
+o  binutils               2.12                    # ld -v
+o  util-linux             2.10o                   # fdformat --version
+o  module-init-tools      0.9.10                  # depmod -V
+
+You might also want to have libncurses5 to have the text mode kernel
+configuration menu, but there are alternatives.
+
+Prerequisites for LTTV 0.6.x installation are :
+
+gcc 3.2 or better
+gtk 2.4 or better development libraries
+  (Debian : libgtk2.0, libgtk2.0-dev)
+  (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
+  (Debian : libglib2.0-0, libglib2.0-dev)
+  (Fedora : glib2, glib2-devel)
+libpopt development libraries
+  (Debian : libpopt0, libpopt-dev)
+  (Fedora : popt)
+libpango development libraries
+  (Debian : libpango1.0, libpango1.0-dev)
+  (Fedora : pango, pango-devel)
+libc6 development librairies 
+  (Debian : libc6, libc6-dev)
+  (Fedora : glibc, glibc)
+
+

 * Getting the LTTng packages
 
 su -
 mkdir /usr/src/lttng
 cd /usr/src/lttng
 (see http://ltt.polymtl.ca/lttng for package listing)
 * Getting the LTTng packages
 
 su -
 mkdir /usr/src/lttng
 cd /usr/src/lttng
 (see http://ltt.polymtl.ca/lttng for package listing)

-wget http://ltt.polymtl.ca/lttng/lttng-modules-0.2.tar.bz2
-wget http://ltt.polymtl.ca/lttng/patch-2.6.12-rc4-mm2-lttng-0.3.bz2
-bzip2 -cd lttng-modules-0.2.tar.bz2 | tar xvof -
+wget http://ltt.polymtl.ca/lttng/lttng-modules-0.4.tar.bz2
+wget http://ltt.polymtl.ca/lttng/patch-2.6.14-lttng-0.5.0a.tar.bz2
+bzip2 -cd lttng-modules-0.4.tar.bz2 | tar xvof -
+bzip2 -cd patch-2.6.14-lttng-0.5.0a.tar.bz2 | tar xvof -

 
 
 * Getting LTTng kernel sources
 
 su -
 cd /usr/src
 
 
 * Getting LTTng kernel sources
 
 su -
 cd /usr/src

-wget http://kernel.org/pub/linux/kernel/v2.6/testing/linux-2.6.12-rc4.tar.bz2
-wget http://kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.12-rc4/2.6.12-rc4-mm2/2.6.12-rc4-mm2.bz2
-bzip2 -cd linux-2.6.12-rc4.tar.bz2 | tar xvof -
-cd linux-2.6.12-rc4
-bzip2 -cd ../2.6.12-rc4-mm2.bz2 | patch -p1
-bzip2 -cd /usr/src/lttng/patch-2.6.12-rc4-mm2-lttng-0.3.bz2 | patch -p1
+wget http://kernel.org/pub/linux/kernel/v2.6/testing/linux-2.6.14.tar.bz2
+bzip2 -cd linux-2.6.14.tar.bz2 | tar xvof -
+cd linux-2.6.14
+cat /usr/src/lttng/patch-2.6.14-lttng-0.5.0* | patch -p1

 cd ..
 cd ..

-mv linux-2.6.12-rc4 linux-2.6.12-rc4-mm2-lttng-0.3
+mv linux-2.6.14 linux-2.6.14-lttng-0.5.0

 
 
 * Installing a LTTng kernel
 
 su -
 
 
 * Installing a LTTng kernel
 
 su -

-cd /usr/src/linux-2.6.12-rc4-mm2-lttng-0.3
-make menuconfig
-  General setup
-    * Linux Trace Toolkit Instrumentation Support
-    M or * Linux Trace Toolkit Tracer
+cd /usr/src/linux-2.6.14-lttng-0.5.0
+make menuconfig (or make xconfig or make config)
+    Select the < Help > 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.
+    Items preceded by [ ] means they should be removed.
+  go to the "Instrumentation Support" section
+    Select the following options :
+    [*] Linux Trace Toolkit Instrumentation Support
+    <M> or <*> Linux Trace Toolkit Tracer
+        It makes no difference for the rest of the procedure whether the Tracer
+        is compiled built-in or as a module.
+    activate :
+       [*] Align Linux Trace Toolkit Traces

     do NOT activate (not ready yet) :
     do NOT activate (not ready yet) :

-        Align Linux Trace Toolkit Traces
-        Activate Linux Trace Toolkit Heartbeat Timer
-              IMPORTANT : This is enabled by default : you must disable it!
+       [ ] Activate Linux Trace Toolkit Heartbeat Timer
+               You may or may not activate instrumentation per facility. They are all
+               selected for logging by default. It can be used as a compile time filter to
+               enable/disable logging of events. It is useful to discard events with a
+               minimal impact on the system and especially useful for now, as the dynamic
+               filter has not been implemented yet.
+    Select <Exit>
+  Select <Exit>
+  Select <Yes>

 make
 make

-make install

 make modules_install
 make modules_install

-
-Depending on your boot loader, you may want to execute :
-update-grub or lilo
+make install

 
 reboot
 
 
 reboot
 

+  Select the Linux 2.6.14-lttng-0.5.0 kernel in your boot loader.
+

 
 * Install the ltt-modules
 
 su -
 
 * Install the ltt-modules
 
 su -

-cd /usr/src/lttng/lttng-modules-0.2
-KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.3 make
-KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.3 make modules_install
+cd /usr/src/lttng/lttng-modules-0.4
+KERNELDIR=/usr/src/linux-2.6.14-lttng-0.5.0 make
+KERNELDIR=/usr/src/linux-2.6.14-lttng-0.5.0 make modules_install
+
+
+* Editing the system wide configuration
+
+You must activate relayfs and specify a mount point. This is typically done in
+fstab such that it happens at boot time.
+
+If you have never used RelayFS before, these operation would do this for you :
+
+mkdir /mnt/relayfs
+cp /etc/fstab /etc/fstab.lttng.bkp
+echo "relayfs         /mnt/relayfs    relayfs rw              0       0"  >> /etc/fstab
+
+then, rebooting or issuing the following command will activate relayfs :
+
+mount /mnt/relayfs
+
+You need to load the ltt-control module to be able to control tracing from user
+space. This is done by issuing the command :

 
 

-note : at this stage, you might want to execute

 modprobe ltt-control
 
 modprobe ltt-control
 

-and you might also want to do this :
+You can automate at boot time loading the ltt-control module by :
+

 echo ltt-control >> /etc/modules
 
 
 echo ltt-control >> /etc/modules
 
 


@@ -98,9 +277,9 @@ echo ltt-control >> /etc/modules
 
 su -
 cd /usr/src
 
 su -
 cd /usr/src

-wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.6.1-16092005.tar.gz
-gzip -cd LinuxTraceToolkitViewer-0.6.1-16092005.tar.gz | tar xvof -
-cd LinuxTraceToolkitViewer-0.6.1-16092005
+wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.8.0-17122005.tar.gz
+gzip -cd LinuxTraceToolkitViewer-0.8.0-17122005.tar.gz | tar xvof -
+cd LinuxTraceToolkitViewer-0.8.0-17122005

 (refer to README to see the development libraries that must be installed on you
 system)
 ./configure
 (refer to README to see the development libraries that must be installed on you
 system)
 ./configure


@@ -111,10 +290,10 @@ make install
 
 
 ***********************************************************
 
 
 ***********************************************************

-** Section 3 * Using LTTV                                **
+** Section 3 * Using LTTng and LTTV                      **

 ***********************************************************
 
 ***********************************************************
 

-* Use graphical LTTV
+* Use graphical LTTV to control tracing and analyse traces

 
 lttv-gui (or /usr/local/bin/lttv-gui)
   - Spot the "Tracing Control" icon : click on it
 
 lttv-gui (or /usr/local/bin/lttv-gui)
   - Spot the "Tracing Control" icon : click on it


@@ -125,6 +304,22 @@ lttv-gui (or /usr/local/bin/lttv-gui)
     - Yes
       * You should now see a trace
 
     - Yes
       * You should now see a trace
 

+* Use text mode LTTng to control tracing
+
+The tracing can be controlled from a terminal by using the lttctl command (as
+root).
+
+Start tracing :
+
+lttctl -n trace -d -l /mnt/relayfs/ltt -t /tmp/trace
+
+Stop tracing and destroy trace channels :
+
+lttctl -n trace -R
+
+see lttctl --help for details.
+
+

 * Use text mode LTTV
 
 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and
 * Use text mode LTTV
 
 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and


@@ -147,9 +342,9 @@ see lttv -m textDump --help for detailed command line options of textDump.
 
 su -
 cd /usr/src
 
 su -
 cd /usr/src

-wget http://ltt.polymtl.ca/packages/genevent-0.1.tar.gz
-gzip -cd genevent-0.1.tar.gz | tar xvof -
-cd genevent-0.1
+wget http://ltt.polymtl.ca/packages/genevent-0.3.tar.gz
+gzip -cd genevent-0.3.tar.gz | tar xvof -
+cd genevent-0.3

 make
 make install
 
 make
 make install
 


@@ -161,16 +356,16 @@ cd /usr/local/share/LinuxTraceToolkitViewer/facilities
 cp process.xml yourfacility.xml
   * edit yourfacility.xml to fit your needs.
 cd /tmp
 cp process.xml yourfacility.xml
   * edit yourfacility.xml to fit your needs.
 cd /tmp

-/usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/yourfacility.xml
+/usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/facilities/yourfacility.xml

 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \

-         /usr/src/linux-2.6.12-rc4-mm2-lttng-0.3/include/linux/ltt
+         /usr/src/linux-2.6.14-lttng-0.5.0/include/linux/ltt

 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \

-         /usr/src/linux-2.6.12-rc4-mm2-lttng-0.3/ltt
+         /usr/src/linux-2.6.14-lttng-0.5.0/ltt

   * edit the kernel file you want to instrument
     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
       of the file.
     - Add a call to the tracing functions. See their names and parameters in
   * edit the kernel file you want to instrument
     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
       of the file.
     - Add a call to the tracing functions. See their names and parameters in

-      /usr/src/linux-2.6.12-rc4-mm2-lttng-0.3/include/linux/ltt/ltt-facility-yourfacility.h
+      /usr/src/linux-2.6.14-lttng-0.5.0/include/linux/ltt/ltt-facility-yourfacility.h