2.1 Patching the Kernel

This discussion concerns a plain vanilla Linux.

• Make sure you have a LTT-supported Linux kernel source installed. If you don't know how to do this, we suggest going through the Linux kernel compilation HOWTO available at www.linuxdoc.org. Do not compile it yet however, although it doesn't matter if you did. It is just a waste of time at this point.


• The LTT source code comes in two parts: 1) the patches for the Linux kernel and 2) the source code for the user-space programs (the log capture program and a log analysis program.) The patches for some kernel versions are available in the single TraceToolkit archive. However, since the version of the kernel changes fairly frequently, it is not practical to keep the patches inside the TraceTookit tar file up-to-date. If, by chance, the patches inside the tar file match the version of the kernel you wish to use, then you are in luck and can proceed directly. Otherwise download the latest ltt kernel patches from an appropriate archive, source repository or mailing list.


• At this point, both the Linux kernel and the Linux trace toolkit source source archives should be uncompressed. If this not the case, change to the root account and type

cd /usr/src
tar xvzf [location of LTT]/TraceToolkit[version].tgz

• Change into the newly created TraceToolkit directory

cd TraceToolkit/Patches

• There will be two patches to apply to the Linux kernel. One for the Relay filesystem, and one for the core LTT code itself. These may be named something like:

• ltt-[kernel-version]-relayfs.patch

• ltt-[kernel-version]-ltt.patch

• Copy the patches to the directory containing the uncompressed kernel source code

cp ltt-*.patch [location of kernel]/linux/

• Apply the patches to the kernel

cd [location of kernel]/linux/
patch -p1 < ltt-kernelversion-relayfs.patch
patch -p1 < ltt-kernelversion-ltt.patch

• Configure and compile the patched kernel. This is documented in the documentation accompanying the kernel and in the Linux kernel compilation HOWTO available at www.linuxdoc.org.
  
  To turn on tracing support, you need to enable the Relay Filesystem, and also enable the Linux Trace Toolkit system itself. The option to enable LTT is not available until RelayFS is enabled, so do that first. If using make menuconfig, the option to turn on RelayFS is under the menu "File systems", and then under the menu "Pseudo filesystems". When turning this on, you can leave "Klog debugging" turned off. Once RelayFS is turned on, the option for Linux Trace Toolkit support is found under the "General Setup" menu.


• If using Trace Toolkit on your local machine (and you are using Lilo), edit /etc/lilo.conf and add an entry for the newly compiled kernel. Typing man lilo.conf should help you do this successfully.
  
  If using another bootloader, follow the instructions for that bootloader to install an alternate kernel for booting on your machine.

2.2 RTAI patch

Prior to doing the following, you need to be familiar with RTAI's installation. See the documentation accompanying RTAI to know more about the installation process.

• Get an LTT supported RTAI version (see the Patches/ directory to see which versions are supported), the corresponding Linux kernel and patch the later using the procedure given with RTAI. With RTAI 24.1.2 you will not find any patches for linux 2.4.0-test10. This one will appear in the rtai directory once you patch RTAI with its corresponding LTT patch. The patch is called "patch-2.4.0-test10-rthal1e". Use this to patch the 2.4.0-test10 kernel then proceed as follows. DO NOT COMPILE ANYTHING YET.

 
• Copy the kernel patch to the directory containing the already patched kernel.

cp patch-ltt-kernelversion-with-rtaiversion-yymmdd [location of kernel]/linux/

• Patch the already patched kernel with the given patch.

patch -p1 < patch-ltt-kernelversion-with-rtaiversion-yymmdd

• Copy the RTAI patch to the directory containing the RTAI source code.

cp patch-ltt-rtaiversion-yymmdd [location of rtai]/rtai/

• Patch RTAI with the given patch.

patch -p1 < patch-ltt-rtaiversion-yymmdd

• Make sure that /usr/src/linux and /usr/src/rtai point to the right rtai and ltt patched linux kernel and the rtai sources respectively. This is important, otherwise the trace module in the kernel won't build.

 
• Configure the kernel, but DO NOT compile it right away. Remember to choose tracing as module and support for RTAI tracing. Also, make sure you DO NOT select SMP support during the kernel config. Currently, only the UP (Uni-Processor) scheduler in RTAI is supported and enabling SMP support will result in the SMP scheduler of RTAI to be used. That scheduler isn't instrumented and even though traces will be generated, they won't be interpreted accurately by the LTT graphic front-end. Note that if you only want to trace the Linux kernel but still intend upon using RTAI, then still enable RTAI tracing and choose the relevant events in the configuration of the trace daemon. This is to make sure time-stamps have meaningful values (this should eventually be fixed).

 
• Configure and compile RTAI.

 
• Finally, compile the kernel and add an appropriate entry to /etc/lilo.conf.

2.3 Building the User-space Tools

The user-space tools build and installation process is managed by autoconf/automake. The usual commands provided by these tools are available.

• Configure the build system. There are a few configuration options specific to LTT, such as the capability to activate/deactivate support for the GTK GUI or support for RTAI traces. To get the complete list of options use configure --help

./configure

RTAI is enabled by default. This will not make any difference for the viewing of normal Linux traces. It will simply enable the event database to recognize another event format along with enabling the visualizer to display RTAI traces correctly.

• Build the package's components


Special Instructions for cross-compiling:

The default configuration assumes that you are compiling the user-space programs for use on the same machine where you are building them. If you are going to collect traces on a machine with a different processor architecture than the one you are compiling on, then you need to cross-compile the tracedaemon program. (You should also have cross-compiled the kernel in the steps above, but that should have been obvious.) The tracedaemon program is run on the target, and must be compiled to execute on the target processor.

If you are not cross-compiling, skip the next sequence of instructions and proceed directly to the 'make' step.

To cross-compile the tracedaemon program, build it manually using a cross-compiling toolchain, by following these steps:


• Make sure the CROSS_COMPILE environment variable is set:
  (ex. export CROSS_COMPILE=/usr/local/arm-linux/bin/arm-linux-)
• Cross-compile the tracedaemon program
  • make -C LibUserTrace CC=${CROSS_COMPILE}gcc UserTrace.o
  • make -C LibUserTrace CC=${CROSS_COMPILE}gcc LDFLAGS="-static"
  • make -C Daemon CC=${CROSS_COMPILE}gcc> LDFLAGS="-static"


Compile the (other) user-space programs.

make

• Install the various components on your system (you will need root privileges). This will install the trace daemon and the visualizer in /usr/bin, the related easy-use scripts in /usr/sbin and the event database and user trace libraries in /usr/lib

make install

The user-space programs and scripts should be installed on your host machine.


Special Instructions for cross-installation:

If you cross-compiled the tracedaemon program, then you need to install it manually in the filesystem of the target machine. You also need to copy the trace helper scripts to the target filesystem. For example, if you NFS-mount the root file system of your target, you could copy tracedaemon and the trace scripts to the exported area of the file system on your host.
• export TARGET_BIN=/target/rootfs/usr/bin
• cp Daemon/tracedaemon $TARGET_BIN
• cp Daemon/Scripts/trace* $TARGET_BIN

That's it! By now, you should have a patched kernel ready to be used, as well as the other software to be able to fetch the results and view them. The next section will now help you use all this!